ドキュメントと戦略

今回ドキュメントについて意見が割れたのでちょっと考えてみたいと思います。

Q.完璧なドキュメントがあれば良いか?
A.もちろん！

Q.私のプロジェクトでは完璧なドキュメントが必要か?
A.いらない。

なぜ完璧なドキュメントがいらないか説明したいと思います。

実は答えは簡単です。手間がかかるからです。

ソースコードとドキュメントが一致しないドキュメントは存在自体悪だと私は思います。
また、もう一つ重要なことは、お客様が必要としているのは、ドキュメントではなく、システムです。

今日他のプロジェクトで、ドキュメントの整備に仕様の半分を費やしているのをあたり前のように話ていたので気になりました。

そのプロジェクトでは、修正が多々あるようですが、まずドキュメントを直してから対応しているそうです。なので、その人はほとんどコーディングをせず、別の方がコーディングを担当だそう。二人プロジェクトなのに…

実際完璧なドキュメントはそれぐらい手間がかかります。もちろん戦略的に、大規模な開発の場合必要だとは思いますが、２−５ぐらいの人数のプロジェクトの場合、きちんとした書類は基本的に必要ないと思います。

さて、ドキュメントがないと、新入りが学ぶまでに時間がかかる、人が抜けたら困るという問題に直面してしまいます。

解決策として、きちんとしたドキュメント戦略を立てるということです。

１．詳細は書かない。
２．大まかな事だけを書く。
３．自分でわかりにくいところは書く。
４．チームで意識を共有し、新入りがはいったり、減ったりしてもチームでサポートできる体制を作っておく
５．コメントとドキュメントの違いも意識する
６．コードをシンプルにする
７．Perlなら、PODで対応。また、シンプルなクラス構成にする。

とかか。

ドキュメントの必要性もわかるが、ドキュメントが最終成果物でないことも意識するべき。