システムの構築に当たっては多くのドキュメントが作成されます。途中の段階では打ち合わせの資料とか報告書などの作成がありますが、最終的には仕様書としてまとめます。
設計書には、外部設計書（基本設計書）と内部設計書（詳細設計書）があります。これらの呼び名はプロジェクトによって異なり、設計書といったり仕様書といったり呼び方は異なります。またこれらをさらに細かくして画面設計書、DB設計書などと読んだりもします。さらにテスト仕様書なども作成します。
外部設計では以下の要素が必要になります。
・目的・概要 ・ユーザインターフェース（画面） ・外部インターフェース ・帳票 ・ハードウエア
他システムとの連携部分、ユーザインターフェースといった外側をまず明らかにします。この段階では、システムの内部はブラックボックスでかまいません。そのシステムの外側に何を提供できるかが重要となります。
また、ハードウエアは、そのシステムの費用を見積もるのに必要となります。また、その物理的配置についての検討も重要です。
内部設計では以下の要素が必要になります。
・ＤＢ設計 ・ファイルフォーマット ・クラス設計 ・プログラム設計 ・その他詳細仕様
システムは、上位目的から順に詳細化していきます。
一番の上位目的は、サービスを提供することで、企業が業績を上げたり社会的に貢献することです。このレベルでは、金銭的な面を考慮して、投資がどれだけで収益がどれだけかという計算を盛り込んだり、あるいは何らかの目的を達成するということがあります。この部分はシステム構築と直接関係しませんが、そういう上位目標を知っていれば、利用しやすいシステムについて考慮できるでしょうし、また励みにもなります。この上位目的を具体化し、サービスをどのように提供するのかというドキュメントが作成されます。ここではユーザ企業側でサービス定義書が書かれます。
この段階で、RFI（Request For Information）をベンダーに提示して、情報を集め、Feasibility（実現可能性）の検討を行ないます。
そしてRFP（Request For Proposal）やRFQ（Request For Quote）を提示し、システムの製作を行なうベンダーを選定し、要求仕様書で要求事項をまとめます。こうなってくるとかなり詳細化してきます。ただしここでは制約事項はあっても、実装方法については言及しません。詳細な要求仕様書は外部設計書に近くなりますが、通常、発注側はそこまでせず、概略だけ述べて、詳細はベンダー側に任せます。
この要求を詳細化し、どのように実現するか、ユーザが検証できる形にまとめたものが外部仕様です。画面インターフェースと帳票の仕様がメインとなります。内部の実装は問いませんが、要求によってはかなり実装に踏み込む場合もあります。DB設計も、概要設計やエンティティの割出しはこの段階でも行われます。ユーザと仕様を詰める際は外部設計を明らかにする段階まで行ないます。
そして、内部設計で、さらに詳細なDB設計やプログラム設計となります。UMLは、このどの部分でも使用できますが、上流であればあるほど概略的になります。
設計書には、必要であれば適切な図や表を載せて理解を助けるようにします。
百聞は一見にしかずといいます。一枚の絵には、文章にすればそれこそ膨大になる情報を含んでいます。料理の味は言葉では語りつくせない情報が含まれています。一般的に感覚経験には膨大な情報が含まれています。
ただ、モデル図にはそんな多くの情報はありません。そもそも絵や写真と違い、記号があるだけで、記号が文章の代わりに使われているに過ぎません。記号の方が、文章よりも正確で、わかりやすいことがあります。また重要な要素をピックアップし、平面的に並べることで、全体の構成を俯瞰できるというメリットもあります。
しかし、詳細を一枚の図で表現できないし、しようとすれば何枚もの図が必要になり、かえって分かりづらくなることがあります。
表を使うと項目は整理され、網羅できますが、洗練されてドロップする情報が出てくることがありま。表に当てはまらないものは、場所を失いますが、文章ならその心配はありません。また線によって境界線が引かれてしまうため、境界線上にある情報は抜け落ちてしまい、関連が切り離されてしまいます。
表を使うことで得るものと失うものがあります。また、表だと、表の枠に入れるため、どうしても文字数を削ることになるため、抽象的表現になりやすいのです。
文章だと頭から順に読んでいけばいいが、表だとバラバラに切り離されたものをくっつけながら読む必要があります。文章の後に表があると、内容が整理されてよいのです。その場合は、表の中はかなり省略した表現である必要があります。
参考：
このシリーズは図解する場合のポイントについていろいろと示唆に富んでいます。
図解言語入門
実際にUMLを使っていない人間、特に会社の上層部の、直接開発をすることのない人は、UMLですべてを表現できるという幻想を持っています。UMLを導入すれば、問題が解決するかのような錯覚を持っている人がいます。UMLは魔法でもないし、目新しいものでもありません。既存のドキュメントを規格統一したに過ぎないのです。
システムの概要をわかりやすく図解しようとすれば、必然的にUMLライクな図となります。そういう心がけをしていたSEがUMLから学ぶところはあまりありません。すでに似たようなものを書いていることに遅かれ早かれ気づきます。
UMLで表現できるのは、概要に過ぎません。図に詳細を描こうとすると、あまりにも複雑になり、目的である概要をつかむことができなくなります。よく参考書で、レイアウトはきれいに見えるが、あちこちにコメントが書かれていて、どこからどう読んでいいか困るものがあります。文章なら、上から下、あるいは右から左、に読んでいけばいいので追っていくのが楽すが、図の中にコメントがあちこちにあると、どう読んでいいか困ります。それと同じで、図は重要なポイントを抽出するだけにとどめることが大切です。
だから、モデルドリブンで、図からソースコードを出力すのには限界があります。もし詳細なソースを出そうとすると、図にすべての要素を盛り込む必要が出てきます。そうなると、図は複雑になりすぎて、直感的に構造をつかむという目的を逸脱することになります。複雑な図は、文章を書くよりも作成に手間がかかります。
あとクラス図はよく使われますがが、業務アプリでは不要です。フレームワークの部分については、その構造を理解するためにあった方がいいと思います。フレームワークに沿って個々の業務を実現していくところは、例として一つ図に描くだけで、それ以外は同じ形式なので要らないでしょう。Actionクラス、サービスクラス、DAOクラスがあり、検索・参照・編集・削除等の機能に沿って同じようなパターンでクラスが作られるだけなので一例だけで十分でしょう。クラス図は多くのIDEで自動生成するので、ドキュメントのページ数を稼ぐのにはよく使えますが。
不思議なのはstrutsにしろ、tomcatにしろ、そのドキュメントにUMLがほとんど使われていないことです。これだけUMLが騒がれているのにもかかわらずなぜだろうかと思います。
仕様の表現には、
１ 文章
２ 図
３ ソースコード
があります。XPでは３に重点を置き、モデリング派、UML派は２に重きを置きます。
読みやすさという点では、どれも一長一短があります。ソースコードの解読は、読む人の熟練度と、ソースコードのきれいさによって変わってきます。熟練していても下手なプログラマーの書いたコードは解読しがたいです。逆にきれいに書かれているなら文書で説明するよりもすばやく理解できます。
そして、１の内容はすべてソースコードに反映されます。ソースコードは、通常、最もシンプルな形で仕様を表現しています。しかしソースコードには見えない情報があります。ソースコードを分析、集計すれば見えてくる場合もありますが、かなり大変です。また、例外処理の中に正常ケースが埋もれて、メイン処理が見えにくくなる場合もあります。
逆にソースコードの内容はフローチャートなど図でほとんどのことが表現できますが、あまりにも細かすぎると、文章を追うよりも理解しがたくなります。
図自体で表現できるのは、構造（関係性）と動きだけです。その名称、中に入るものについては、文字を使う必要があります。無理に何でも図にする必要はありません。
UMLは基本的に制御系のアプリケーションに適していると思います。画面操作とデータベースが中心になる業務系では、ER図と画面遷移図、画面定義は必須だと思います。UMLに、画面遷移図、画面定義がないのはなぜか分かりませんが、UIは非常に重要な要素です。ユースケースのかなりの部分に関与しています。要求事項にUI操作が多くあり、またUIから要求を推定できます。同一の機能に対するViewが非常に多い場合はこの限りではありませんが、多くの場合ドメインとUIの関係は深いものがあります。
テスト仕様書は、仕様書をチェックリストに書き換えたもので、内容はほとんど同じものです。通常、具体化するので、さらに細かくなります。例えば仕様書に「0〜100までが有効な値、それ以外はエラーとする」と書いている場合、テストケースでは、0,100という正常な境界値、そして異常値として、-1,101という境界値に加えて、$%&などの記号を入力、未入力といったケースで、最低でも6個のテストケースを必要とします。
テスト仕様書を仕様書とする場合、テスト仕様書ではチェック項目だけで、背景や補足説明がしにくく、仕様に関する全情報が載らない可能性があります。また、テスト仕様書には、仕様書にはないテスト方法について記述することになります。また、項目に分割しているので、書かれている内容に重複がある場合があります。
結局目的が違います。仕様書は仕様を定義し、また理解させることですが、テスト仕様書はそれに沿ってテスト項目を消化していくことにあります。
テスト仕様書では、端的に項目だけ書き、詳細は仕様を参照という形にすることもしばしばあります。
仕様書とテスト仕様書で内容が重複するのは、好ましくないので、できれば共通化して、一箇所修正すれば両方とも反映されるようにしたいところです。外部設計書、内部設計書、単体テスト仕様書、結合テスト仕様書、システム資料書、ユーザマニュアル、管理者用ユーザマニュアル、と同じようなことを書いているドキュメントが多数あり、一箇所使用が変更になれば全部直さなければならない羽目になります。
あるプロジェクトでは使用をすべてAccessに放り込んでいるそうです。しかし、これだと図との連携が難しいし、正式なドキュメントに整形する上でいろいろ難題がありそうです。
