このエントリでは、ソースコードとドキュメントの分離する理由について説明します。

JsDoc(JavaDoc) は、Code に Spec や API Spec をマークアップして埋め込む強結合のスタイルです。
一方、WebModule の推奨しているスタイルは、Code と Spec を分離し、Spec は Web 上に配置する疎結合なスタイルです。

個人的に「もっと、こう…なんとかならないかな?」と思っている部分です。
ここは、各自の経験や使い方で、感じ方に個人差があると思います。

• JsDoc が認識できない構文があると、その部分のドキュメントが抜け落ちてしまう
  • ドキュメントツールの都合でソースコードを修正する作業が辛い
    • JsDocToolkit → JsDoc3 で発生した非互換性がこれに該当
• 詳細な説明やサンプルコードを埋め込もうとするとどんどん長くなり、コードの見通しが悪化する
  • よく出来たサンプルコードを考えるのは時間もかかるので、後から書きたいし、できれば分離して別の場所に置きたい
• 自動生成されるHTMLと、他の文書やコンテンツ(設計書,画像,動画)の連携が非常にやりづらい
  • 「ドキュメント内に外部へのリンクや相互リンクを後から追加したい場合は、どうすれば?」「コードのリビジョンを上げてまでリンクを埋めるほどの価値はあるのか?」といった判断をしたくないし、そんな事で悩みたくない。
  • リビジョンが上がってしまうという理由で「後でまとめてやります」と、その場で更新がされなくなり、チリツモでドキュメントがいつの間にか嘘化している事も
• コードフリーズしたプロダクトだとドキュメントをアップデートする機会がなくなってしまうことも
• API ドキュメントが社内サーバに設置されると、利用する気になれない
  • 自宅や移動中に見れないと、ちょっと試してみようという気にならない
  • Google で検索できないライブラリやフレームワークは、結局利用されないのではないか? という気になり敬遠してしまう

以下は、WebModule の Spec をデザインする段階で出てきたニーズとウォンツ + 愚痴です。

• 静的なドキュメント(更新されないHTMLの自動生成)をやめたい
  • ソースコードにはキーワードだけ埋め込んで、後から書けるもの、余計なもの、頻繁に追加/更新されるものはコードから切り離したい
  • スピード感が欲しければ、ドキュメントは後から拡充すればよい
  • HTML化されたドキュメントを配置する場所や公開範囲で悩みたくない
• DevTools のコンソールに URL を出力するとクリックできる特性を活かそう
• API ドキュメントは、もっと画像や動画を活用しよう。Webサービス を活用しよう
• GitHub と連携しよう。GitHub の Wiki を活用しよう。GitHub を中心にヘルプのエコシステムを構築しよう
  • Wiki なら外部との相互リンクも気軽にできる。ソースコードに手をいれる必要もない
  • ネットに晒す事で人の目が増える。改善するチャンスも増える
  • サンプルコードを書きやすい環境を整え、全体の質を高めよう
• 試されない → 実績できない → 採用されないのループはいやだ
  • 死産がいやなら、最初から公開すればいい
• 移動中の5分, 会議前の10分といった、ちょっとした隙間時間でドキュメントを記述したりチェックできるようにしよう

つまり、ドキュメント生成ツールの都合を気にせず、外部のWebサービスと連携した動的な仕組みを取り入れて、何処にいてもドキュメントを見たり書いたりできるようにしたいのです。