ドキュメントはいつ書き、いつ修正すべきか

アジャイル開発の有名な指針には「詳細なドキュメントより、実際に動くコードを優先する」というものがあり、その影響かどうかは分かりませんが、開発中にドキュメントを書かないプロジェクトも多いと聞きます。

そもそもアジャイル開発の対局にあるウォーターフォール型の開発であったとしても、一度フィックスしたドキュメントを修正するのは容易ではなく、一度設計プロセスを通過してしまったプロジェクトではドキュメントの修正は後手に回ってしまいやすく、結局誰も見ないという事態が発生しがちです。

こういう問題は一概に答えを出すことは難しいものですね。以下の文章は、１人〜数人程度のチームで小規模開発を行う場合に限定した意見として読んで頂ければ幸いです。

ドキュメントを最初に全部作ってフィックスさせてしまうのも、あるいは開発中ほとんど（あるいは全く）手を付けずに、最後になってコードに合わせてドキュメントを作るのも両方良くないと思います。もちろんそんなことは分かっていると仰るでしょうが、実際のプロジェクトでは特に後者のパターンは結構頻繁に行われていますよね。

ドキュメントを書く利点の１つは、コードを変更する手間よりもドキュメントを変更する手間のほうが少ないため、いきなりコードを書いてしまってから修正するよりは効率よくデザインが出来るということです。しかしながら、逆にドキュメント上だけで実際のソフトウェアの詳細な動作や操作感を想像するのには限界があり、ドキュメントを詳細に作りすぎると今度は実際その通り作ってみたら期待と違った、なんてことも起こります。

だから考え方としては
「難なく想像できる詳細度まではドキュメントのみを先に書き、それより詳細な部分のドキュメントは開発しながら書く」
という感じがいいのではないかと思ってます。

例えばWebアプリケーションで言うと、画面遷移や画面のざっくりした大まかな構成はコーディングを初める前に書き、それより先はコーディングを進めつつ書く、みたいな感じですかね。

ドキュメントの更新を最後にまとめてやるパターンは実に多いんですが（そして気持ちもよく分かりますが）、ひたすらドキュメントだけを作るのは大変で退屈な作業である上に抜け漏れも発生しやすいので、やはり開発中に頻繁に更新すべきでしょうね。

理想的には「ドキュメント駆動」的な開発ができるといいと思ってます。まずドキュメントに変更を加え、それに基づくテストを書き、それから実装コードを書く、っていう手順です。現在僕が取り組んでいるプロジェクトではこの進め方を実際試してみるつもりで、このテーマについてはまた書くと思います。

※この記事について指摘・意見・提案・感想などありましたら下のコメント欄にどうそ。