詳細設計書（前半）

表紙

   図2はDUNGEONの表紙です。一部では成果物を厚さで評価するという風潮もありますが、基本的に必要事項が記載されているなら、設計書のページ数は少ない方が読みやすいし取り扱いも楽です。そこで、表紙と更新履歴を1枚にまとめたフォーマットにしています。

---

   表紙には、システム名、サブシステム名、機能名のほか、作成会社と担当者を記入できるようにしています。これら基本的な記述項目については、プロジェクト単位で変更することも許可しています。たとえば小規模なプロジェクトであればサブシステム欄は不要となりますし、大規模なプロジェクトであればもう1階層サブシステムを用意する必要があるかもしれません。なお、設計書の作成日は、更新履歴の1行目に記載するということにしています。

更新履歴

   更新履歴の記載メッシュは、設計書のバージョン／レビジョン管理の方針により異なります。ちょっとした変更があってもバージョン（レビジョン）を更新するのであれば、細かな更新履歴がたくさん記載されることになります。一方、ある程度の変更をまとめてレビジョンアップするのであれば、メッシュは粗くなります。DUNGEONでは、後者の方針に基づいて管理しており、ユーザ提出やレビューなどのタイミングにあわせて更新履歴を追加することにしています。

目次

   図3は、DUNGEONの目次と概要です。上記と同じようにページ数を少なくするという理由で目次と概要を一緒にしていますが、分量が多ければ別ページにしてもかまいません。

   目次のポイントは、ページ番号の付記と記述項目の細かさです。目次をタイトルだけとするか、タイトルとページ番号を記載するかは、プロジェクトリーダーの裁量にまかせることにしています。

   もちろんタイトルとページ番号を両方とも記載する方が読みやすいのですが、設計書は追記が多いのでその度にページ番号を振り直す必要があります（Wordなら、自動的に番号を振り直すように作成できるのですが…）。ユーザ提出まではタイトルのみとし、設計書が完成してユーザ提出時にページを記載するという運用が多いようです。

   また、記述項目の細かさについても、プロジェクトリーダーの方針で決定します。テンプレートで用意されている大項目だけにするか、その下のサブ項目まできちんと記述するかは、目次作成・メンテナンスの手間と読みやすさのトレードオフとなります。

概要

   「他人の書いた設計書はわかりにくい」とよく言います。いきなり規定フォーマットどおりに詳細仕様が大量記述されている設計書は、確かにわかりにくいものです。それは、設計者本人は暗黙の了解としていることでも、他の人にその前提がないからでしょう。時が経っている場合は、設計者自身でも自分で作成した設計書を理解するのに時間がかかります。

   その原因の最たるところは、"概要"が記載されていないことです。この設計書で設計する"機能"がどういう目的のもので、誰がどう使うのか、そういう前提知識を最初に記載するだけで、ぐっとわかりやすくなります。そのため、DUNGEONでは、冒頭部分に"概要"を記載し、第三者が読んでも理解できる"わかりやすい設計書"を目指しています。



各シートに最終更新日を付けるか

   設計作業中は、かなりの頻度でちょこちょこ変更が入ります。通常、これらの変更をある程度まとめた段階でドキュメントがバージョンアップされ、表紙の変更履歴に記載されます。そのため、各シート上にも作成会社や担当者のほかに変更日を記載し、そのシートの情報がいつ変更されたかをきちんと表す方式もよく取られています。

   しかし、DUNGEONでは各シート上に変更日の欄は設けませんでした。これは、これまでの経験で欄を設けてもきちんと変更日をアップデートしない設計者が多かったためです。本来は、それを運用で徹底させるようなアプローチを取るべきなのでしょうが、その負荷と効果を天秤にかけて議論した結果、変更日欄を設ける代わりに、前バージョンからの変更箇所を青字で記述する方が実践的と考えたのです。このように割り切るかどうかは、各社なりの方針があると思いますので、テンプレートを参考にする際は考えてみてください。