テクニカルなドキュメントを書くなら何を書くべきか、という記事。
Writing great documentation: what to write.
- チュートリアルを作れ
- 素早いのを：使い手が20分以内に何かしら達成感を得られるように
- 簡単なのを：Foolproofな内容にしておく
- ただし能力不十分な人は挫折させるようにする
- その技術の大体の「感じ」が掴めるように、いろんな側面を見せる
- トピックガイドを作れ
- よくあるユースケースを網羅する
- これだけ見れば使い方が分かるようにする
- リファレンスを作れ
- トピックガイドには些末すぎる引数や動作の詳細などを載せる
- リファレンスをチュートリアルやトピックガイドの代わりにするな！
- Javadoc的なのは使うな
- 手で書き、手で編集して、手で整理したドキュメントには勝てない
元記事でも言われてるが、トピックガイドというのは公式ドキュメントに含まれてることが少ない気がする。そういえば一番役に立つのは全体を見渡せるし具体例にも触れられるトピックガイドなのかも。たとえばプログラミング言語やフレームワークなどの場合、いくらリファレンスが充実していても、トピックガイドがないと膨大なモジュールのうちどれを使えばいいのかが分からなかったりする。
ドキュメントの自動生成については元記事と同意しかねるかな。リファレンスなら自動生成でいいでしょと思う。残りの部分はそもそも手で書くしかないわけだし。
Djangoのドキュメントが優れてるらしい。僕がこれまでに見た中で優れたドキュメントといえば…。うーむ。何があったかな。The Subversion Book？CodeIgniterのドキュメントも良かったと思う。
