無駄なドキュメントは書くな

ひたすら実装に関するドキュメントをしこしこ書いている人がいるが、好きで書いているわけではなく、書かされているのかもしれないけれど、そーゆー無駄なドキュメントは書くな。時間の無駄である。実装は日々変化する。それに追従する形でドキュメントが更新されるということはない。断言する。実装に関するドキュメントと最新の実装は常に食い違っている。いまだかつて同期したことがない。無駄なドキュメントを書く時間があるならコードを洗練しろ。無駄なドキュメントを書く時間があるならコードをドキュメントにしろ。
ソフトウェア工学の教科書にドキュメントの重要性が書いてあるからといって信用してはいけない。ウオーターフォールモデルが商用ソフトウェア開発の現場で役にたたないように、実装に関する詳細ドキュメントは百害あって一利なしである。
コードがドキュメントだ。 http://capsctrl.que.jp/kdmsnr/wiki/bliki/?CodeAsDocumentation

人月の神話―狼人間を撃つ銀の弾はない (Professional Computing Series)

http://groups.google.co.jp/group/fj.comp.oops/msg/b0df491f0d07a689?q=yoshioka%40best.com&start=50&hl=ja&lr=&rnum=52

今，手元に第２版を置いているのですけど，ドキュメントについては１５章に書いてあると思うのですが，そこで「フローチャートの呪い」ということで，その役割を否定しています．また「自己文書プログラム」ということでプログラムのコードの中に文書を入れる事を提案してます．

”プログラム文書は悪名高いほどに貧弱で，そのメンテナンスはさらにひどい．プログラムの変更が，すみやかに正確にそしてそのまま紙の上に記述されることはない．”
”主要な目的は，文書作成の負担を最小化することだ．”
…
ブルックスの第２版では，漸増的構築モデルということで，マイクロソフトの「毎晩構築」アプローチを紹介してます．デイリービルドとかナイトリービルドとか呼ばれているやつですね．これは毎日毎日ビルドを繰り返して，徐々に機能を洗練しいくアプローチです．
毎日のビルドでは常に動くプロダクトが得られます．時として機能の後退（リグレッション）が発生しますが，毎日ビルドしてリグレッションテストを流していますからすぐに発見できます．いつ失敗してもいいのだけれどそれを発見してすぐに修正するというプロセスが組み込まれています．
このプロセスのダイナミズムを理解しないとなかなかシュリンクラップの現場の勢いを理解できないかなと思います．
一つのプロダクトが出荷されるまでにものによっては数百回，あるいはそれ以上ビルドされて，常に修正されるというイメージです．

http://web.archive.org/web/19990423145139/http://www.best.com/~yoshioka/d/98/i980227.html
とかも読め。

なお最新版は

人月の神話―狼人間を撃つ銀の弾はない (Professional computing series (別巻3))

みたいです。（出版社が変わっただけで内容は一緒だと思う。人月の神話）