ドキュメントとして何を書くか?

僕の考えは、以下のような感じ。 (1) ドキュメント(設計書だろうが仕様書だろうが)は、「誰に何をどう伝えるべきか」を考えれば、何を揃えればいいかは自然と決まってくる。そして、誰が読んでも意味がないと判断されるドキュメントは意味がないので書かない。 (2) 「基本設計書」や「詳細設計書」や「外部設計書」や「内部設計書」という言葉があるが、肝心なのは「誰に何を伝えるか」であり、伝えたいことや認識あわせの単位でドキュメントが作られればそれでいい。それらをまとめて「○○設計書」とするかどうかは、顧客がそうしたければ好きにすれば良い(そこまでやる義務は開発側にはないと思う)。 (3) アーキテクトの仕事は、各作業者が何をしたらいいか迷うことなく作業ができるように「決めごとをしていくこと」。その決めごとは、すべてドキュメント化されるべきであり、そのためには「誰に何をどう伝えるべきか」を考えていけば、記述される内容のレベルや粒度などは、各作業者のロールをちゃんと定義してあげれば、おのずと決まってくる。 (4) 完全な自動テストソリューションは、まだ世の中に登場していない、という認識を現在は持つべき。なので、「システムがどう挙動すれば正しいのか」という話は、JUnitやSeleniumなどのコードを書いたからといって「満たした」などと考えてはいけない。「こう操作したらこうなる」というドキュメントを作っておくべきで、それを最終的に「正しい仕様書」に育てることが最優先事項。 特に(3)と(4)の認識の甘いアーキテクトが多すぎる。「自称アーキテクト」という人間であればあるほど、その認識の甘さは宇宙レベル。 プロトタイピングとか、 プログラミングファーストとか、近年ではプログラムの動作をまず確認してもらって、妥当であればそれで良し、的な風潮が見え隠れするけど、プロジェクトが完了して成果物が顧客に渡る際には、 ・ ○○という人々に□□という目的で△△というドキュメントを書きました。 ・ このシステムは○○という操作をすると△△という動きをすることを良しとしました。 という2点が揃っていることが、開発側の最低限の責務だと思う。 (注) 上記は「釣り」ではなく、大真面目に書きました。

このエントリーをはてなブックマークに追加

Yoichiro

(よういちろう)