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

id:hyoshiok:20050510さんのエントリーを読んで全くその通りだと思った。

断言する。実装に関するドキュメントと最新の実装は常に食い違っている。いまだかつて同期したことがない。無駄なドキュメントを書く時間があるならコードを洗練しろ。無駄なドキュメントを書く時間があるならコードをドキュメントにしろ。

ソフトウェア工学の教科書にドキュメントの重要性が書いてあるからといって信用してはいけない。ウオーターフォールモデルが商用ソフトウェア開発の現場で役にたたないように、実装に関する詳細ドキュメントは百害あって一利なしである。

自分が見聞きしたモノから判断すると、実装とかけ離れている＆誰も読まないドキュメントはIT業界ではあふれていると思います。
さすがに紙に印刷しなくなっただけましですが、ExcelやらWordやらのドキュメントが納品物がたくさんあり、実はソースコードと全然同期が取れていなかったりということは良くあるのではないでしょうか。

必要のないドキュメントは主に以下の理由により増えていると推測します。

• 過去の慣習に従いそのままドキュメント一式が決められている。（社内標準など）
• 会社として対外的にｘｘｘマークを取得しています、ｘｘｘメソドロジーを採用していますとアピールするために必要になるドキュメントがある。
• アウトソーシングなどで、発注元にソースを読むことをできる人がいない場合が増えてきている。（かといってドキュメントを読んで分かるわけでもない）
• 新しい簡潔なドキュメンテーション・設計手法が納品物を管理するような人々に浸透していない。

このあたりは、いろいろと事情があるのかもしれませんが、誰も読まないドキュメントに注ぐ時間を成果物の品質アップにあてた方がお客さんも幸せだろうに。。

ついでに同じくid:hyosiokaさんの日記で紹介されていた

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

ですが、以下のような内容でOSプロジェクトのマネージメントと、大規模プロジェクトのマネージメントという二つの切り口で読むことができるので興味のある方はぜひ読んでみてください。

著者のブルックスは、IBMにおいてOS/360メインフレーム用のオペレーティングシステム開発マネジャーを経験し、現在はコンピュータサイエンス学科の大学教授。本書では、OS/360用のオペレーティングシステム開発で生じたさまざまな問題をもとに、プロジェクト管理の問題点と今後どのようにすべきかを論じている。

ちなみMonaでAPIのドキュメントをあまり書いていないのは、上の件とはあまり関係ありませんのであしからず。