SourceCodeWithoutDocument

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

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

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

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

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

• JsDoc が認識しない構文があると、その部分のドキュメントを書く手段がなくなる(遅延評価や動的な変更など)
• 詳細なサンプルコードを埋め込もうとすると、ソースコードが長くなり見通しが悪化する
  • 1関数が1画面に収まらないと辛い
  • ドキュメントの修正でリビジョンが上がり、ノイズ(動作に無関係なログ)が増えるのは辛い
  • よく出来たサンプルを考えるのはコードを書くよりも時間がかかるので、後からサンプルコードを追加したい
• API ドキュメントを自動生成しただけで「ドキュメントはある。ドキュメントを書いた」と主張する人がいて、胃が痛くなる
• テキストの他に、画像,動画で説明したい事があるが、それらの情報を利用し辛い
  • ツールで自動生成する HTML と、外部に配置する HTML の二重管理になると面倒
    • 場合によっては、最初から外部の HTML に一元化したほうが低コストなのでは? という疑問がある
• 社内のサーバに API ドキュメントを設置されると、移動中や自宅から見れなくてやる気がでない
  • ツールが生成する HTML が地味に大きく、ファイル数も多いため気軽に配布しづらい(テンプレート次第で5MBを越えるケースも)
  • API ドキュメント自体に秘匿性はないはずなのに、社内じゃないと見れないのは、ちょっと意味が分からない
    • Google で検索できないライブラリやフレームワークなんて誰が利用するんだろう

大別すると、

1. ドキュメントの修正でリビジョンが上がるのは辛い。それを理由に修正しない事があるのも辛い
2. 良いサンプルコードを誰かが書いてくれた場合に、そのコード(URL)に対してソースコード側からリンクを張れないのが辛い
3. 認証がかかった場所にAPIドキュメントを設置されると辛い。どこでも見れたりググれないのは辛い

です。

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

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

です。

Help.js では、

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

といった運用に関する部分を、github(markdown)に寄せることで、色々と解決できるのでは? と考えました。

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