SourceCodeWithoutDocument

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

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

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

JsDoc(JavaDoc)の運用の、この辺が辛い

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

• 遅延評価や動的な変更など、JsDoc が認識しない構文があると、その部分のドキュメントが抜け落ちてしまう
  • 自動生成のためとはいえ、書かなくても良いようなアノテーションを大量に埋め込む作業がつらい
• 詳細な説明やサンプルコードを埋め込もうとすると、アノテーション部分がコードそのものより長くなり、見通しが悪くなる
  • コードブロックが1画面に収まらないと、スクロールが多発して辛い
  • よく出来たサンプルコードを考えるのは時間がかかるので、後から追加するか、別の場所に置きたい
• 自動生成されるAPIドキュメントと、設計書,画像,動画の連携がやりづらい
  • 自動生成される HTML がファットでファイル数も多いため気軽に配布しづらい(数MBオーダーになる)
• 置き場所に困ったあげく、社内のサーバに API ドキュメントを設置されると、移動中や自宅から見れず、使う気が起きない
  • API ドキュメントやサンプルコードに秘匿性はないはずなのに、ちょっと意味が分からない
  • Google で検索できないライブラリやフレームワークなんて誰が利用するんだろう?

大別すると、

1. JsDocが認識しない構文を気にしながらコードを書くのはつらい
2. 外部の Webサービスと気軽に連携しづらい
3. 一部の人しか見れない場所にドキュメントを設置されるのは辛い。どこでも見れるようにすべき

ようするに、github で markdown で書きたいのです。

Help.js で実現したかったこと

• APIドキュメントを社内に隠すという考え方を根底から変えたい
  • コードは守る価値がある(かもしれない)が、APIドキュメントには無い。最初から外に出すべき
• HTMLの自動生成をやめよう
  • API ドキュメントやサンプルコードは、ソースコードと切り離そう
    • コードにキーワードだけを埋め込んで、後から書けるもの,余計なもの,頻繁に追加/更新されるものはコードから切り離そう
    • スピード感が欲しければ、ドキュメントは後から拡充しよう
  • ドキュメントの見栄えの修正や、つまらないミスでリビジョンを上げるのはやめよう
  • 自動生成で「とりあえず作りました」なドキュメントは要らない。最初から人の手で書いたほうが早い
• DevTools のコンソールに URL を出力するとクリックできる特性を活かそう
• API ドキュメントは、もっと画像や動画を活用しよう。Webサービス を活用しよう
• GitHub と連携しよう。GitHub の Wiki を活用しよう。GitHub を中心にヘルプのエコシステムを構築しよう
  • ネットに晒す事で人の目が増える。改善するチャンスも増える
  • コードの使い方を説明するような、よくできたまとめサイトが生まれたら、Wikiからそちらにリンクを張ろう
  • サンプルコードを書きやすい環境を整え、全体の質を高めよう

です。

Help.js では、

1. ドキュメントをどこにホストするか
2. どうやって配布するか
3. 書式はどうするか

といった運用部分を、github と markdown に寄せてデザインしています。

今よりも気軽にサンプルコードを書けるような環境が整備されて行くことで、より良いドキュメントやサンプルコードが増えると良いですね。