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 なら外部との相互リンクも気軽にできる。ソースコードに手をいれる必要もない
- ネットに晒す事で人の目が増える。改善するチャンスも増える
- サンプルコードを書きやすい環境を整え、全体の質を高めよう

です。

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