皆さんのお手元には基本設計書の雛型などは整備されておりますでしょうか？都度フォーマットから用意しているような状況でしょうか？
私は2019年3月よりフリーランスエンジニアとして活動を始めましたが、 様々なプロジェクトに参加いたしますと、意外と設計書のテンプレートは整備されていないということです。
そもそも設計書が存在していないとか、メンテ不能なPDF版で存在するとか、設計書のフォーマットがばらばらでメモ書きのような雑なものだったりなど。
そのような現場に入った際に利用可能なテンプレートがあると便利だと思いませんか？
書籍でも設計書の書き方や設計書として揃えるべきドキュメントの種類を学ぶことは可能です。むしろ、書籍のほうがまとまっており、初めての方が書き方を学ぶのであれば書籍のほうが良いかもしれません。
しかしながら、それらの書籍の付録として配布されている設計書テンプレートにおいて、実際に現場で使えるテンプレートは今のところ出会ったことがありません。
表紙と目次、見出しがちょっと記載されているだけで、何も無いに等しい状態のものがほとんどです。
例えば以下のようなものです。
上記の状態では結局ゼロから書くのと変わらないですよね。
設計書を書くのが初めての人は書籍等で書かなければならない要素について学べても、フォーマットを一からそろえるのは大変だと思っております。
ということで現場で使える設計書テンプレートを提供できれば、以下のような方々にとって有益なものになるのではと考えております。
- フリーランスエンジニアとして独立しようと考えている方
- 設計書を初めて書く方
- 会社内でまだ決まったテンプレートが無い方
- 他のエンジニアはどういう設計書を利用しているのか気になる方
もちろんテンプレートだけ提供しても基本設計の全体像がわからないと思いますので、簡易的なものではありますが説明を加えつつ提供していきたいと思います。
なお、テンプレート一式はnoteで公開中になります。当該記事と同じ説明を載せておりますので、テンプレートをダウンロードされたい方はnoteをご確認ください。
基本設計書のテンプレートはExcelかWordか
ITエンジニアが記述する設計書の多くはExcelが多い印象です。
Excelファイルのセル幅を縮めたいわゆるExcel方眼紙ベースの設計書ですね。
というのも画面項目やDBのテーブル項目など、何かと表形式で書くものが多いため、Excelのほうが扱いやすいという背景があります。
また、画面のスクリーンショットもExcelのほうが比較的添付しやすいです。
しかしながら、お客様環境毎にプリンターが異なるため、Excelで記述すると印刷範囲のズレが生じ、それらの体裁を整えるのに非常に手間がかかるデメリットがあります。(※ 印刷設定はプリンターに依存します。印刷しないかもしれませんが納品物ですので)
また、セルに記述した文章が印刷してみると隠れてしまっていて印刷されないということも起きやすいです。
実際に過去の経験上、以下のような問題が生じ、最後に設計書全体の体裁を修正するだけで1週間程度時間をかけることがありました。
- 列幅のズレを修正
- セル内の文章が印刷範囲外へ飛び出しているのを折り返しに修正
- セル内の文章が印刷すると隠れてしまう箇所の修正
- 上述の修正に伴う行幅の調整とそれに伴う1ページあたりの印刷範囲の修正
- Excel関数で参照している箇所のリンク切れ修正(シートの追加、削除、コピーを行っていると発生しがち)
ということで今回は印刷時の体裁面で悩まされることが無いように、Word文書でテンプレートを用意しようと考えています。(用意しました。)
※ Wordが最適解というわけではありませんが、読み手が労せず読めてメンテナンス可能なツールで作成するということには意味があります。
※ エンジニアがチームのエンジニアの為に用意する文書であれば、ファイル形式はそこまで問題にはならず、ただのテキスト文書に箇条書きでもExcelでもマークダウンでも正確に伝えられるなら問題ないと思います。
基本設計書に必要な各種仕様書
基本設計書に必要な仕様書は以下の通りです。
- 命名規則
- 機能一覧
- 処理機能記述
- 画面一覧
- 画面仕様書
- 画面遷移図
- 項目ラベル名一覧
- エラーメッセージ一覧
- 帳票一覧
- 帳票仕様書
- ファイル一覧
- ファイル仕様書
- 外部インターフェース一覧
- 外部インターフェース仕様書
- バッチ処理一覧
- バッチ処理仕様書
- システムメール一覧
- システムメール定義書
- DBテーブル一覧
- DBテーブル定義書
- DBビュー一覧
- DBビュー定義書
- ER図
- コード一覧
- セキュリティ仕様書
- ワークフロー一覧
- ワークフロー定義書
- アプリケーション仕様書
おおよそ上記が書ければ大抵のシステム開発において必要な情報が揃うと思います。
予算が限られている、あるいは非常に小規模なシステム開発においては最低限以下の設計書があれば十分だと個人的には考えております。
- 命名規則
- 機能一覧
- 画面一覧
- 画面仕様書
- 画面遷移図
- 帳票一覧
- ファイル一覧
- 外部インターフェース一覧
- 外部インターフェース仕様書
- バッチ処理一覧
- バッチ処理仕様書
- システムメール一覧
- システムメール定義書
- DBテーブル一覧
- DBテーブル定義書
- ER図
- コード一覧
- アプリケーション仕様書
※ 昨今ではフロントエンド開発とサーバーサイド開発の分業が進んでいることもあり、基本設計時にある程度API設計まで済ませているケースもありますが、どちらかというと詳細設計に近いものですので当該記事では割愛します。
命名規則
システムの機能や画面、帳票などに識別IDを付与する際のIDの付け方や、DBのテーブル名、項目名の付け方(IDはXXX_id、コードはやXXX_code、名称はXXX_nameなど)などを定義します。
機能一覧
社員情報一覧、社員情報詳細、組織情報一覧、組織情報詳細・・・といったシステム内で登場する機能を一覧表に列挙します。
記述する粒度としては、一つの画面として成立するような機能、メニューの単位になるような大枠の機能で記述します。
社員情報を一覧表示する画面単位の機能として、例えば社員情報を登録する画面で組織情報を入力する際に、入力補助機能として組織情報検索のポップアップ画面を表示する機能などがありますが、このようなポップアップ画面も一つの機能として機能一覧に記載します。
しかしながら、社員情報一覧画面内にある社員情報の検索機能や出力結果の並び替え機能など、そのような細かい機能の単位で記述することはほとんどありません。
処理機能記述
機能一覧に記載した「機能」の処理の流れをフローチャートなどの図や説明を用いて記述します。
例えば社員情報一覧であれば「画面を初期表示する」、「検索をする」、「検索条件をクリアする」、「検索結果を並び替える」、「検索結果の一覧表からデータを選択して詳細画面を表示する」などといった当該機能で起きるアクションに基づく「処理」それぞれの説明を記述します。
初期表示であれば、メニューから当該画面に遷移して、デフォルトの検索条件である〇〇で社員情報マスタからデータを取得し、社員情報一覧に結果を描画する、あるいは初期表示時は検索結果を表示せず、検索条件の入力欄を描画するなど、処理の流れを記述します。
画面一覧
システムで登場する画面を一覧表にまとめます。
例えば社員情報一覧画面、社員情報詳細画面、社員情報入力補助画面、組織情報一覧画面、組織情報詳細画面、組織情報入力補助画面などを一覧にまとめます。
社員情報の詳細情報を表示するような「詳細画面」は、照会画面、入力画面、入力内容確認画面、登録完了画面など、同一レイアウトで項目の入力可否の違いだけの画面パターンがあることが多いです。
これらは一つ一つの画面として定義する場合もありますが、モードの違いとして一つの仕様書にまとめられることが多いです。
レイアウトが大きく異なる場合や、わけたほうが記述しやすい場合もありますので、記述する粒度はプロジェクトや案件によって少し異なります。
画面仕様書
画面一覧に記述した画面ひとつひとつの項目の並びや画面で発生するイベント、入力チェック仕様にDBの保存先など細かな定義を記述します。
画面がユーザーインターフェースの中心となっている以上、当該仕様書が基本設計の大半を占めています。
画面仕様書とDB設計があればシステム機能のほとんどを構築できると言っても過言ではないほど重要な仕様書です。
画面仕様書を見ればどのような入力項目があり、どのようにデータベースへ保存するのかがわかります。
画面遷移図
画面と画面のつながりを表した図になります。
例えば共通メニューから社員情報一覧画面や組織情報一覧画面へ遷移し、一覧画面から社員情報詳細や組織情報詳細などの個々の詳細情報画面へ遷移するといった情報を図で記述します。
よくある図としてはオートシェイプの四角と矢印を使って、四角を画面、矢印を遷移先の画面への繋ぎとして記述するものです。
項目ラベル名一覧
全画面で利用する項目名の一覧になります。
例えば担当者名であったり担当者氏名だったり、同じ項目に対して似たような別の名称をつけてしまうことがありますが、一覧にまとめることでこのような表記揺れを防ぐことができます。
また、実装面において多言語対応されるケースも多いと思います。昨今のフレームワークにおいては項目名にIDを指定すると、指定言語に応じて紐づくラベル名に自動変換してくれます。
上記のような機能を利用する場合にも日本語の項目名と英語の項目名を同じIDに紐づけて一覧で定義します。
エラーメッセージ一覧
エラーコードとエラーメッセージを一覧で定義します。
こちらも項目ラベル名一覧と同様に日本語エラーメッセージ、英語エラーメッセージを同一のIDに紐づけて定義します。
ワーニングも当該一覧に定義します。
帳票一覧
システムで発行する帳票の一覧になります。
帳票とは例えば申請書のような主に印刷して利用する固定レイアウトのものになります。
帳票仕様書
帳票一覧に記載した帳票のレイアウトを定義するものになります。
画面仕様書と同じように項目の並びや、DBのどのテーブルからどのように値を出力するのかの定義に加え、印刷する際の用紙サイズや余白の定義も記載します。
ファイル一覧
システムで出力するファイルの一覧になります。
主にユーザ操作によって出力するファイルを記述するものであり、ログファイルなどシステムの裏側で作られるファイルは含まれません。
例えばCSVファイルのようなデータ出力を主としたファイルを一覧に記述します。
ファイル仕様書
ファイル一覧に定義したファイルの詳細を定義するものになります。
ファイルがテキストファイルなのかバイナリファイルなのか、テキストファイルであれば文字コードが何かなどを含め定義します。
外部インターフェース一覧
連携する外部システムの一覧になります。
例えばGoogle Driveとの連携、クラウドサインといった外部サービスとの連携、自社の基幹システムとの連携等々、別のシステムとの連携を行う場合に記載します。
外部インターフェース仕様書
外部インターフェース一覧に記載した外部システムとの連携方法や連携するデータの項目レイアウトなどを定義します。
バッチ処理で実装されることもあり、その場合はバッチ処理仕様書に詳細処理を記述し、連携するデータの項目レイアウトのみを外部インターフェース仕様書に記載します。
バッチ処理一覧
システムで実行するバッチ処理の一覧になります。
例えば日次でシステムから案内メールを送信したり、バックアップ処理を行ったり、比較的多量のデータを処理するプログラムをメインのシステムサービスとは別に独立実行するような処理の一覧です。
処理に時間のかかるものが多いため、基本的にはユーザアクセスの少ない時間帯に実行することが多いです。
バッチ処理仕様書
バッチ処理一覧に記載されたバッチ処理の詳細を記述します。
日次なのか週次なのか月次なのかといった実行タイミングと、どのような処理を実行するのかを記述します。
システムメール一覧
システムから送信する通知メールの一覧になります。
例えば「非標準ソフトウェアの利用申請承認依頼通知」など、システム上送信される通知にどのようなものがあるかを記載した一覧になります。
システムメール定義書
システムメールの宛先、件名、本文について記述します。
宛先はメールアドレス固定のケースよりも例えばログインユーザであったり、申請者や承認者といった何かしらの「ユーザ」を示す言葉で定義することが多いです。
本文についても、固定の文章部分と差し替えて利用する部分がわかるように記述します。
DBテーブル一覧
データベース(DB)のテーブル名一覧です。
社員情報テーブルや組織情報テーブル、それらを紐づける所属組織テーブルなどシステムに必要なデータを保存するテーブルを列挙します。
DBテーブル定義書
DBテーブル一覧に記載したテーブルの項目レイアウトを定義します。
レコードを一意に特定するためのキー項目は何か、項目のデータ型は数値なのか文字なのか日付なのかといった情報を記述します。
このDBテーブル定義書をもとにCREATE TABLE文などを生成するため、重要な設計書の一つになります。
DBビュー一覧
DBのビューの一覧です。
ビューとは簡単に説明しますと、テーブルとテーブルを予め結合して、一つのテーブルのように見せるのがビューになります。
DBビュー定義書
DBビュー一覧に記述したビューの詳細を記述します。
ビューを構成するテーブル名、それらの結合条件、および項目名を列挙します。
ER図
DBテーブルの関連図になります。
例えば社員情報と組織の関連を表す場合、「社員」からみて所属する「組織」は複数あります。(例えばaさんがA部とB部を兼務するケース)
「組織」からみて所属する「社員」も複数ですね。(例えば、A部にはaさん、bさん、cさんと複数の方がいます。B部にもaさん(兼務)、dさん、eさんと複数の方がいます。)
上記のような関係を四角と線を用いてデータのつながりを表すのがER図です。
データ1つに対して同じくデータが1つ紐づくのか1対1の関係、複数紐づく場合は1対多の関係になります。
「多」を表す場合は、専用の記号あるいは「*」を利用します。
例えば【社員】1-*【所属組織】*-1【組織】のようにオートシェイプなどで図を構築していきます。
この図があるとテーブル間の関連が理解でき、データをどのように管理するかを把握することができるため、重要な設計書の一つになります。
※ 個人的にはWordのオートシェイプではなく、VSCodeでdrawioをインストールし、記述したER図を画像取り込みして利用すると良いと思います。
コード一覧
システム全体で利用するフラグや区分の値を一覧化したものになります。
例えば社員の分類として1:社員、2:契約社員、3:ビジネスパートナーのように区分を設けることがあります。
これらの区分の値を一意に示すコード(1,2,3)とコードの名称(社員、契約社員、ビジネスパートナー)を記載します。
セキュリティ仕様書
システム全体のセキュリティ方針を記載します。
XSS対応、パスワードソルト、社員情報の暗号化、社員情報一覧を表示するページのキャッシュ化無効等々どんな対策を実施するのかを記述します。
ワークフロー一覧
システムで利用するワークフローを一覧にまとめたものになります。
社内IT機器の利用申請や研修申込申請などといった申請処理と承認処理を行う機能が必要な場合に記述します。
ワークフロー定義
ワークフロー一覧に記載したワークフローの詳細を記述します。ワークフロー機能が無ければ記述することはありません。
例えば、PCの外部モニタを追加調達する際に、利用者がPCモニタの利用申請を行い、部門長が承認し、総務の機器調達チームのリーダーが承認するといった流れを定義します。
誰が申請を行い、誰が承認するのか、申請する際、承認する際におけるシステムメールの有無、購入金額等によって承認者のルートが変わるのか否かなどを記述します。
アプリケーション仕様
アプリケーション仕様はシステムを構築する上での基本ルールを定義したものになります。
例えば以下のような事柄を記述します。
- システム構成(webサーバ、DBサーバ、帳票サーバ等々の構成)
- ファイル配置方式(ソースファイルのフォルダ階層など)
- 開発モデル(プログラミング言語やフレームワークなど)
- 処理フロー方式(画面とサーバ間の処理の流れ)
- メッセージ方式(多言語対応の有無、メッセージの表示方法)
- 文字コード
- ログ出力方式
- 例外処理方式
- 入力チェック方式
- 制御方式
- 認証方式
- 認可方式
- セッション管理
- DBアクセス方式
- 採番方式
- 排他制御方式
- ファイルアップロード、ダウンロード方式
- メール送信方式
フレームワークを採用する場合は基本的にはフレームワークの仕様にあわせた動きとなりますので、利用するフレームワークにおける特徴や注意事項を中心に記載します。
基本設計書のテンプレートサンプルについて
簡単ですが基本設計書の構成につきましては上述にて説明いたしました。
設計書のテンプレートにつきましては、以下noteにて公開中ですので是非参考にされてください。
上記で紹介させて頂いた設計書28ファイルすべてダウンロード可能にしております。
以上です。
