[IM]ドキュメントの方針

INTER-Mediatorについて、ドキュメントをもっと充実させるべきという声は常に聞かれますし、その通りだと思います。とは言え、いかに効率的に作るかを考えないと、本体以上に破綻するかもしれません。ドキュメントはテストドリブンでの制作はできないのですから。そういうわけで、当面の方針をきちんと作り、そして書いて、実行することにします。

以前は、最終的には「パターン」への落とし込みが重要ではないかと考えていましたが、パターンとして落とし込むには、知の集約が必要であり、一定期間に少人数でできることではありません。既存のパターンを使うとしても同様です。

現在考えているのは、プラクティスの充実です。たぶん、サンプルや例題というのもプラクティスの一つなのでしょうけど、サンプルは説明がしづらいとか、デバッグ用に無意味な組み合わせの機能があるとか、プラットフォームを初めて見る人には辛いものです。その意味で「例題」なのですが、fluent 2014に言ったときにEmber.jsのセッションで言われていたのは「フレームワークはコミュニティのプラクティスを取り込まないといけない」というところで、ピンと来ました。例題の題材は、コミュニティにあるものを採用しないといけないということです。機能説明になっては本末転倒になるというところでしょうか。そういうわけで、プラクティスという言葉がきっかけで、やるべきことが整理された気がします。

ソフトウエアプラットフォームの開設のための文書にどのようなタイプのものがあるかを考えてみました。マーケティング的なことを抜きにして、利用者(通常は開発者)に対するコミュニケーションのためには次の4つがあるのではないかということです。

  • 仕様の記述:当然必要、網羅性が求められる
  • チュートリアル:手を動かして学習、INTER-Mediatorでは有償コンテンツとして用意
  • プラクティス:これから充実させたい
  • パターン:抽象度の高いノウハウ

今は、プラクティスを充実させる段階であり、それが一段落してからパターンに進むのが手法としてはステップを踏む感じがするのです。

プラクティスとして作成する予定のテーマは次の通りです。もちろん、みなさんからの要望やアドバイスを期待します。とは言え、あまり重いものはプラクティスではなく、実システムになってしまい、微妙なところです。以下の5、6はえらく長くなりそうですし、むしろ上級向けのチュートリアルのテーマではないかとも思います。

  1. 検索をしてその結果を一覧表示する
  2. 一覧表示と詳細表示を行き来する
  3. アンケートなどの入力のみのページ
  4. 伝票形式のページを作成する
  5. 会員制サイト(ヘビーか?)
  6. カート(不要か?)

一方、「こういう作りのページを簡単に作れることは意図していない」という、ある意味のアンチプラクティスも記述が必要と考えています。たとえば、こんなテーマです。とりあえず、1つだけです。

  1. 入力フォームの後の確認ページが不要な理由

ということで、プランを立てないと前に進めない気がするので、とりあえず、書いておこうと思います。