仕様書はどこまで詳細に書くべきか
投稿日:2007年08月08日 作成者:yasunaka
だいぶ以前に、?設計書に書くべき範囲という似たようなタイトルでブログを書いていますが、今回は「詳細化」という観点から考察してみましょう。なおここに取り上げていないドキュメントについては、下のいずれかに相当するものとして考えてください。
昔は詳細設計書というのがあって、フローチャートなどという懐かしい図とともにかなり細かいレベルのドキュメントを書いていましたが、最近では詳細設計書は書かないのが当たり前になってきたと思います。（ただしミッションクリティカルな分野については違うかもしれません）
理由の１つにはオブジェクト指向の普及などにより、詳細設計書とソースコードがほぼ同義語と考えられるレベルになってきており、「２つのドキュメント（詳細設計書とソースコード）」の二重メンテナンスは避けるべきだと考えられるようになってきたこと、そして、コンピュータリソースが貴重だった時代とは異なり、昔では考えられないような高度な統合開発環境が誰でも使えるようになってきており、詳細設計書のレベルのことはソースコードで十分じゃん、というのがはっきりしてきたため、ともいえると思います。
では他の設計書はどうでしょうか？ 基本設計書や概要設計書はその名の通り、詳細化しては「いけない」ものです。ここに詳細なことを書き込んでは、読み手が本当にそれを読んで押さえるべきツボを押さえられなくなります。基本設計書には基本的なこと、概要設計書には概要を書くべきであって、それ以上のものを書く場所ではありません。詳細化を避けることによって、これらの設計書が読みやすくなり、プロジェクト全体の方向性を定めるコンセンサスを取るための道具として、またプロジェクトへの新しい参加者向けの導入書として、またテスト設計する上での基準としても役に立つようになります。
では外部設計書はどうでしょうか？ これは十分に詳細化されてしかるべきものでしょう。もしシステム間インターフェースとなるデータベース項目やファイルフォーマットなどが最終化されたものがない状態で開発し始めると、後になって大きく回り道をする羽目になります。ユーザーI/Fも同じです。ユーザーI/Fが詳細化されていない状態で開発が進んだ場合、操作の一貫性が損なわれたり、同じような処理があちこちに散らばる結果になります。
ただし外部設計書も最初から詳細化されたものがいきなり出てくるわけではありません。通常はいくつかの段階を踏んで、徐々に詳細化していくものだと思います。最後に残ったドキュメントは詳細化されているべきだ、というだけで、途中の中間成果物まで詳細化されているべきだ、とは申しません。
トム・デマルコさんの書いた書物のいくつかには、ユーザマニュアルこそが究極の設計書だと書かれています。ユーザマニュアルは、ユーザが読む視点で書かれた外部設計書といえます。外部設計書としてはユーザマニュアル程度の詳細化が必要だ、ということかもしれません。