設計書の概要説明は意外と重要

はじめに

今回からは、機能設計書の標準フォーマットについて例題を用いて解説していきます。よろしければ、皆さんが自社で使用しているフォーマットと比較してみてください。追加すべきエッセンス、もしくは削っても良いと思われる項目がありましたら、フォーマットを改良するヒントにしていただければと思います。今回は、まず概要を解説します。

機能設計書の標準フォーマット

前回、設計書作成CAD「SI Object Browser Designer(OBDZ)」を開発するに当たり、社内外の設計書を片っ端から集めて比較検討したと述べました。その結果、決定したOBDZの標準フォーマットが表1です。

表1：機能設計書のフォーマット(画面)

右欄は、基本設計書と詳細設計書にそれぞれのページが含まれるかを表したものです。第5回でデータモデリングの作業が(教科書的には)概念モデル→論理モデル→物理モデルと流れることを解説しましたが、機能設計書の作成も図1のように概要設計書→基本設計書→詳細設計書という順になります。そして、データモデリングで概念モデルをあまり作成しないように、通常は概要設計書を作成せずに基本設計書に概要部分も含ませます。

図1：機能設計書作成の流れ(データモデリング対比)

一般に基本設計書と詳細設計書は別々のドキュメントではなく、基本設計書に詳細内容を“肉付け”したものが詳細設計書となるので、この2つを作る際にムダは生じません。どこまでを基本設計書の範囲にするかは企業やケースによって異なるので、表1の〇の範囲は柔軟に変わり得ると考えてください。

では、表1のページ構成を基に、機能設計書の標準化と標準フォーマットについて見ていきましょう。

設計書CADの作業イメージ

今回はOBDZの画面を用いて設計書フォーマットを解説するので、最初にCADで設計するイメージを共有しておきます。OBDZは世の中で使われている一般のCADと同じく、コンピュータ画面で設計作業を行い、設計書として印刷できます(図2)。具体的な方法としては、設計データをExcelで用意した標準フォーマットに落としてExcelファイルを作成するので、後はExcelの機能として印刷したりPDFファイルを作成したりできます。

機械設計や建築設計などのCADと異なるのは、通常、プログラマはわざわざ設計書を印刷せずに、拡張モニタに設計画面を表示しながらプログラミング作業をすることです。そのため、これから解説するフォーマットは、紙に印刷されたイメージではなく、CAD画面のレイアウトが中心となります。

図2：画面で設計作業を行い、Excel設計書に出力

One Fact One Place(ワンファクト・ワンプレイス)

もう1つ頭に入れておいて欲しいことは、紙の設計書と違い、One Fact One Place(1つの事実を示すデータは1つの場所にしか存在させない)であることです。Excelなどに記載した設計書だと「画面レイアウト」ページに書いた内容と、「コントロール(項目)一覧」ページに書いた内容がくい違ってしまうことがままあります(One fact Two Placeですね)。

一方、CADは1つの項目(例えば、図3の「引合番号」)が「画面レイアウト」と「コントロール一覧」で同じデータに紐付いているので、どちらかで変更・削除すればもう一方でも変更・削除されます。Excel設計書の場合に画面レイアウトから「引合番号」項目を削除しても、コントロール一覧からは削除されないことを思い浮かべてください。

図3：CADはOne Fact One Place

＜＜Column＞＞One Fact One Place

One Fact One Placeは、第5回で説明したDOA(Data Oriented Approach)の基本概念です。図4を例に説明しましょう。プロスペクト登録画面に対応するテーブルが「プロスペクト」、受注入力画面に対応するテーブルが「受注」だった場合、何も考えずに設計すればプロスペクト登録画面の「プロスペクト登録者」と受注入力画面の「受注担当者」はそれぞれのテーブルに個別にセットされます(図4左）。

図4：正規化によりOne Fact One Placeを実現

しかし、「プロスペクト登録者」も「受注担当者」もどちらも社員なので、ちょっとでもリレーショナルデータベースの正規化をかじったことがあれば、考えるまでもなく図4右のように社員マスタの「社員」をそれぞれのデータと紐づけ、3つのテーブルの「社員」が1つ(One Fact)を指すように設計します。こうしておけば、例えばある社員が今月獲得したプロスペクト件数と受注件数をパッと出すことができますし、社員が退職した場合も「プロスペクト」「受注」テーブルはそのままで「社員マスタ」テーブルに退職フラグを立てるだけで済みます。

なお、One Fact One Placeの概念は、ERPでも「業務データの統合」という意味合いでよく使われるようになりました。ただし、ERPの場合は様々な理由であえて非正規化を行っているデータも多いので、実際はベンダが謳っているほどOne Fact One Placeではありません。でも、データを連携させることにより実質的にOne Fact One Placeを実現しているのです。

One Fact One Placeにより、あるページで書いた内容は他のページに反映されます。表1の各ページの項目の関連を図示すると、図5のようになります。「画面レイアウト」と「コントロール一覧」の関係は図3のように相互反映(図5では両方向矢印)ですが、その他のページも関連性があり、設計作業の2度手間や矛盾発生がない仕組みになっています。各ページの関連については、次回以降に順を追って解説します。

図5：機能設計書の項目関連性

機能設計書の解説

さて、ここからは表1の各ページのフォーマットについて、「販売管理システム」の「プロスペクト一覧画面」を例題として解説していきます。

(1)表紙と概要

画面1は、OBDZで作成した「プロスペクト一覧画面」の「基本情報」タブです。機能コードや機能名、作成者など、表紙に表示される項目に続いて概要欄があります。機能仕様書を見る人(ユーザーやプログラマ、保守担当者、そして未来の自分自身)に対して、最初にどのような機能かを説明することが有効なのは異論がないはずです。しかし、エンジニアという生息域に住む人たちは、精緻なロジックを組み上げることは得意でも、ふわっと全体を俯瞰してアナログで語ることは苦手のようで、概要欄がない、もしくは概要欄があってもちゃんと記述されていない設計書が多いです。

画面1：プロスペクト一覧画面の基本情報タブ

最初に概要や役割を理解した上で設計書を読む方が、誰が読む場合でもずっと理解が早まります。くれぐれも、この「概要欄」をおろそかにしないようにしましょう。おそろかにしないとは、つまり、概要欄を用意するだけでなく、概要記述の良いお手本を示し、設計者にレクチャーをするという運用を徹底することです。

(2)変更履歴

画面1には「履歴」欄があります。設計書は、作成している途中も、完成した後も、さらに保守運用に入ってからも、何度も変更されます。その際に、このような履歴欄を設けてどこが変わったかひと目でわかるようにしておくことは重要です。トラブルの原因でよくあるのが、変更したことが読み手(ユーザーやプログラマー、他の設計者など)に伝わってなく、後で発覚して「え、変更したの?」と大ごとになるケースです。

実は「変更履歴」も上記の「概要」と同じ悩ましい課題があります。つまり、変更したのにきちんと変更履歴を書かない、いちおう書いてあるが何を変更したのかパッとわからない、まとめるのが苦手でコメント行が文字であふれかえってしまう、などがよくあるのです。はい、ここもエンジニアの苦手領域なので、お手本とレクチャーを忘れないようにしてください。

おわりに

今回から機能設計書の標準フォーマットの解説に入りました。今回はさわり部分の概要と変更履歴のみを説明しましたが、次回は図3に登場した「画面レイアウト」と「コントロール一覧」について、気を付けるべきポイントを解説します。