SourceCodeWithoutDocument

ソースコードとドキュメントの分離

Help.js は、ソースコードとドキュメントを分離し、ドキュメントを Web 上に配置するスタイルです。

一方、従来のやり方である、JsDoc (JavaDoc) は、ソースコードにドキュメントをマークアップして埋め込むスタイルです。

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

遅延評価や動的評価の部分など、JsDoc が認識できない構文があると、その部分のドキュメントが抜け落ちてしまう
詳細な説明やサンプルコードを埋め込もうとするとどんどん長くなり、コードの見通しが悪化する
- よく出来たサンプルコードを考えるのは時間もかかるので、後から書きたいし、できれば分離して別の場所に置きたい
自動生成されるHTMLと、他の文書やコンテンツ(設計書,画像,動画)の連携がやりづらい
APIドキュメントが社内サーバに設置されると、利用する気になれない
- 自宅や移動中に見れないと、ちょっと試してみようという気にならない
- Google で検索できないライブラリやフレームワークは、結局利用されないのではないか? という気になり敬遠してしまう
- API ドキュメントやサンプルコードをガードする理由が分からない。惰性でやっているなら、悪習なのでやめたほうがいい

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

以下は、Help.js の機能と運用をデザインする段階で出てきたニーズとウォンツです。

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

ということです。

時代は GitHub と Markdown を軸に動いています。
より気軽にサンプルコードを書ける環境が整備され、より良いドキュメントが増えると良いですね。