PR

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

2020年4月2日(木)
梅田 弘之(うめだ ひろゆき)

はじめに

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

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

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

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

<<麻里ちゃんの設計奮闘記>>チェックアウト、チェックイン
  • 先輩:麻里ちゃん、なんだか機嫌悪いみたいだね。
  • 麻里あれ、顔に出ていますか。実は、設計書を変更したのに変更履歴を書かない人が多くて困っているんです。
  • 先輩:う~ん、Excelの設計書あるあるだね。
  • 麻里え、これって運用の問題だからCADを使っても一緒だと思うんだけど…。
  • 先輩:CADの場合は、チェックインの仕組みを使って、少し工夫しているんだ。
  • 麻里チェックインって、バージョン管理システムの仕組みですよね。
  • 先輩:うん。リポジトリからチェックアウトして最新バージョンを取得し、変更作業を行ってから、チェックインして変更内容を反映する、おなじみの仕組みだね。
  • 麻里リポジトリってどういう意味だっけ?
  • 先輩:英語のRepositoryの意味は「貯蔵庫」。システム開発では、設計データやプログラム、デザインなどの成果物を一括管理しているものをリポジトリと呼んでいるよ。
  • 麻里誰かがチェックアウトしていると、他の人は参照のみっていう排他制御ができるんですよね。
  • 先輩:そうそう。で、話を戻すとOBDZは専用CADなので、わざわざバージョン管理ツールを使わずに自身でこの仕組みを持っているんだ。そこで、チェックインの際に自動的に画面2のような変更履歴記入ダイヤログを出すようにしている。このおかげで、うっかり変更履歴を書き忘れることが防げるんだ。

  • 画面2:チェックインの際に変更履歴を記入

  • 麻里なるほど~。でも、それでも“無視”して書かないって人もいますよね。
  • 先輩:まあね。ツールがどんなに頑張っても、最後は使う人しだいではある。でも、Excelベースの設計書のときと比べると、みんなきちんと書くようになったよ。
  • 麻里ダイアログにそんなに効果があるなら、先輩もパソコンをシャットダウンするときに「今日は禁酒!」とか表示出したらどうですか。
  • 先輩:お、良いね! じゃあ、お礼に麻里ちゃんには立ち上げたとき「今日はダイエット!!」を出してあげるさ。
  • 麻里……。やっぱり、お互いにこういうことはやめましょう!

おわりに

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

著者
梅田 弘之(うめだ ひろゆき)
株式会社システムインテグレータ

東芝、SCSKを経て1995年に株式会社システムインテグレータを設立し、現在、代表取締役社長。2006年東証マザーズ、2014年東証第一部上場。

前職で日本最初のERP「ProActive」を作った後に独立し、日本初のECパッケージ「SI Web Shopping」や開発支援ツール「SI Object Browser」を開発・リリース。日本初のWebベースのERP「GRANDIT」をコンソーシアム方式で開発し、統合型プロジェクト管理システム「SI Object Browser PM」、アプリケーション設計のCADツール「SI Object Browser Designer」など、独創的なアイデアの製品を次々とリリース。最近は、AIを利用したサービスに取り組んでいる。

主な著書に「Oracle8入門」シリーズや「SQL Server7.0徹底入門」、「実践SQL」などのRDBMS系、「グラス片手にデータベース設計入門」シリーズや「パッケージから学ぶ4大分野の業務知識」などの業務知識系、「実践!プロジェクト管理入門」シリーズ、「統合型プロジェクト管理のススメ」などのプロジェクト管理系、最近ではThink ITの連載をまとめた「これからのSIerの話をしよう」「エンジニアなら知っておきたいAIのキホン」を刊行。

「日本のITの近代化」と「日本のITを世界に」の2つのテーマをライフワークに掲げている。

連載バックナンバー

Think IT会員サービス無料登録受付中

Think ITでは、より付加価値の高いコンテンツを会員サービスとして提供しています。会員登録を済ませてThink ITのWebサイトにログインすることでさまざまな限定特典を入手できるようになります。

Think IT会員サービスの概要とメリットをチェック

他にもこの記事が読まれています