ドキュメントは必要？

傲慢SE日記さんの「ドキュメントは必要？」という記事を見て、私も思うところを書いてみたいと思います。
本当はコメントに書こうと思ったのですが、長くなりそうなので記事にしてみました。

私が以前いた職場ではウォーターフォールで仕事をしていたのですが、たしかに設計者に書かれたドキュメントには抜けや間違いが多く、結局はドキュメンとソースが乖離したものになってしまいます。
ですので私も、傲慢SEさんのように「どうせドキュメントには不備があってソースが正しいのだから、ドキュメントはいらないのではないか」と考えていました。

ですが、初めてプロマネと設計を担当（人数が少ないのでプロマネと設計を兼務しました）し、私のこうした考えを一変させる経験をしました。

そのプロジェクトのメンバは6人で、殆どのメンバがスキルに自信を持ち、殆どのメンバがドキュメントの作成を苦手としていました。
そこで私はメンバと話し合い、アジャイル手法の一つであるXP でプロジェクトを進めることにしました。
これでドキュメントを書く工数や製作工数が削減できると考えたのです。

結果から言うと、これは大失敗でした。
XPの各プラクティスに対して、次のような問題が発生したのです。（ここに挙げている問題点は私たちの未熟さから発生したもので、XPの問題ではありません）

ストーリーの不備による要求変更の増加
プロジェクトの終盤にさしかかっても要求変更が相次ぎました。
これは私が基本設計しているにもかかわらず、私が所属する会社が孫受けだったことが原因だと思います。このような立場では、顧客の常駐どころか対面も叶いません。
プロジェクトの終わりのほうで知ることになるのですが、私たちが作成したドキュメントやプロトタイプは、プロジェクトの終盤になるまでエンドユーザに見せられていませんでした。定期的に元請のSIerに提出していたにもかかわらずです。
この結果、プロジェクトの終盤になっても要求が変更され、その結果仕様変更が相次ぎました。
また、ストーリーが明確でないため、メンバは最後まで仕様を理解しませんでした（理解しようともしませんでした）。
反復形開発による仕様変更の増大
XPではドキュメントで顧客にコミットメントを取らないため、必ずといっていいほどプロトタイプを公開したときに仕様変更を要求されます。これは間違ったことではなく、本来、XPは「仕様変更を受け入れよう」という考えのもとに作られているのだと思います。
ですが、このプロジェクトでは仕様変更するたびに、「なぜ俺が作ってから仕様変更が発生するんだ」とメンバから不満が続出しました。
テスト駆動開発の形骸化
最初はユニットテストをきっちり行っていたのですが、仕様変更がある度に徐々にテストケースと仕様が食い違うようになり、最終的には誰もテストケースを更新しなくなってしまいました。
結局、メンバは（目先の）工数削減のためにテストを省略してしまったのです。
その結果、品質は目に見えて低下していきました。
YAGNIを取り違えたやっつけ仕事の増加
YAGNIとは、「You Aren't Going to Need It.（今必要なことだけ行う）」ことです。
これは私は、「将来必要になるかどうか分からない機能を今作りこむのはやめよう」ということだと思っています。
これをメンバは、「エラー処理も今は必要じゃないから作るのはやめよう」と考えたようです。このため、ソースコードには大量にTODOとかかれたままでエラー処理を考えられることなく作られていきました。
ドキュメント工数の削減の失敗
ドキュメント工数を削減できると考えていたのですが、結局納品物として、基本設計書、画面設計書、テスト成績書等、普段作っているものと同じだけのドキュメントが必要でした。
それも検収の関係上から、プロジェクトの中盤で完成したドキュメントの提出を求められました。
結局、「ドキュメントを書かなくてもよい」ということにはなりませんでした。

これらの問題点は、単純にプロジェクトがアジャイルプロセスに即していないだけだったかもしれませんし、私やメンバの力不足があったのは確かです。ですが、私はこれを機に仕事の進め方を考え直すこととなりました。
その後に読んだある本（題名は失念してしまいましたが、確かスティーブ・マコネルの本だったと思います）（Joel Spolsky の「ジョエル・オン・ソフトウエア」でした）に、ドキュメントについての重要性が書かれていました。
内容も詳しくは忘れてしまいましたが、その本に学ぶところがあり、私はウォーターフォールを適用すべきガイドラインと、ウォーターフォールを適用する場合の注意点を次のように考えています。（これらのポイントは私の中でまだ未完成ですので、これからも変えて行きたいと思っています。）

ウォーターフォールを適用すべきガイドライン

お客様にアジャイル手法を受け入れてもらえない場合
製作者が働いている会社が元請ではない場合（製作者が元請のオフィスに常駐している場合はOK）
製作者の技量が低く、また教育するだけの余裕がない場合
アジャイル手法が理解できていないメンバが半数以上いる場合

ウォーターフォールを適用した場合の注意点

フェーズごとにお客様に確実にコミットメントを取ること
期限だからといって、完成していないのに次のフェーズに移行しないこと
ドキュメントを書く人はドキュメントを書くスキルを持っていること
ドキュメントの保守に専任の担当者をつけること

リストの中でも太字にしましたが、ウォーターフォールの中での問題点の一つは、「ドキュメントを書くスキル」の必要性が見過ごされていることだと思います。ドキュメントを書いた人はドキュメントの読者が理解できない場合、往々にして「読む人の頭が悪い」のが原因だと考えてしまいがちです。ですが本当にそうでしょうか？私は、ドキュメントの書き手が悪い場合のほうが多いと思っています。
ちなみに、ウォーターフォールを適用した場合の注意点は、先述の本と「アジャイルソフトウェア開発の奥義」に学ぶところが大きいです。

最後に、私が傲慢SEさんと同じような状況に置かれたときにとった行動は、「ドキュメントを読んで理解できない点や矛盾点をリストアップして送りつける」というものでした。
設計者のプライドを傷つけないよう、文句をつけるというより、単純に分からないとか論理的に矛盾しているというスタンスをとるように気をつけました。
そのリストで相手が非を認めた項目については、早急にドキュメントを修正してもらうようにしました。
この方法が正しいかどうかは分かりませんが、ウォーターフォールの下流工程を担当する上での一つの対策だと思っています。


Joel Spolsky, 青木靖
Joel on Software