業務システムを作るためには、様々な工程をクリアしなければなりません。システムの核を決める要件定義に始まり、全体の俯瞰に落とし込む基本設計、具体的な流れを作る詳細設計を経て、開発、テストと進んでいきます。
どれも重要な工程ですが、中でも重要なのが詳細設計です。ここを過ぎれば本格的に開発が始まってしまうのですから、プロジェクトにおける帰還不能点と言っても過言ではないでしょう。そのため可能な限り読みやすい、優れたドキュメントにしなければなりませんが、それにはどう言った点に気を付けるべきなのでしょうか。
今回はMicrosoft Office Wordで仕様書を作る場合を例として、フォーマットの基本についてご紹介しましょう。
①目次
まず始めに用意するべきは、全体の目次です。
何ページにどんなことが書いてあるか、章立てと見出しを記載し一目で分かるようになっていなければなりません。ドキュメントの顔とでも言うべき箇所のため、間違いは許されず、少し修正が入っただけでも常に最新化されている必要があります。
考えるだけで大変な作業ですが、Wordを使えばこの点は簡単に解決出来ることをごぞんじでしょうか。実はWordには、ドキュメント内の見出しやアウトラインを読み込み、目次を自動作成してくれる機能があるのです。しかも、そうして作られた目次にはリンク機能も備わっているため、Ctrlキーを押しながらクリックすることで、目的のページまで一瞬でジャンプすることも可能です。
②修正履歴
目次の次は、ドキュメントの修正履歴を記載しましょう。
複雑な要件を実現する詳細設計書を、一度で完璧に仕上げることなどまず出来ません。クライアントや上長と一緒に何度も手直しをする必要があるため、それを管理する修正履歴がないと、後々混乱してしまうことでしょう。
記載するべき項目は、そう多くはありません。見出し番号とページ、それから簡単な概要欄程度です。あまり長く書きすぎると非常に読み辛く、管理もしにくくなるので、なるべく簡潔にするよう心がけましょう。
また、履歴にもリンクを貼ると、より読みやすいドキュメントになります。少々面倒ですが、是非設定しておくと良いですよ。
③概要
その次に書くべきは、この仕様書の簡単な概要です。ここでは具体的なシステム定義ではなく、プログラムの目的とその実現方法を書くと良いでしょう。
要件定義よりも具体的に、基本設計よりも簡潔に、１ページの半分に収まるくらいを目安にしてください。「基本設計を要約したもの」というイメージで書くと、分かりやすい概要が作れるかも知れません。
④フローチャート
フローチャートは絶対必須ではありませんが、あるとコーディング担当者に喜ばれます。設計者の頭の中にあるイメージを図に落とし込むことで、コーディング担当者との意志の疎通が容易になります。
大切なのは、複雑で細かいチャートを書きすぎないことです。実際のコーディングでは想定外のケースが色々と出てくるので、あまり詳細なフローをここで書いてしまうと、矛盾が生じてしまうのです。そうなれば、コーディングに合わせていちいち修正しなければならなくなり、管理が非常にし辛くなってしまいます。
概要欄の記載内容を、そのままフローに起こすくらいがちょうど良いでしょう。
⑤動作環境
忘れがちなポイントとして、ＯＳなど動作環境の記載も必要です。複雑なシステムになると、クライアントだけではなく、別サーバー、別ＯＳでの運用も考慮しなければならなくなります。そのためＯＳや前提となるソフトウェア、そのバージョンなどを細かく記載しておかないと、後々問題になる可能性があります。
⑥想定パフォーマンス
また、プログラムの実行の基準となるパフォーマンスについても記載すると良いでしょう。ここでは「どのくらいのパフォーマンスになるか」を予想して書くよりも、「どの程度のデータ量で、どのくらいの処理時間に納めるべきか」を書くのがポイントです。
予め具体的な数字を決めておくことで、パフォーマンス検証や改善に時間を費やす必要がなくなり、余裕のあるスケジュールで開発出来るようになります。
⑦機能詳細
ここまで様々な前提を書くことで、ようやく機能詳細を書き出すための準備が出来たと言えるでしょう。
データ検索や分岐条件など、具体的な作りを細かく記載し、プログラムの骨子を構築していきます。この時の気を付けるべきポイントは、大きく３つに分けられます。
・１．箇条書き
複雑な工程を長々と文章で説明しても、なかなかスッと理解するのは難しいことです。要所で箇条書きを活用すると、グッと読みやすい仕様書になります。
・２．データパターン
文章でシステムを説明する以上、受け手の解釈でどうとでも受け取れる、曖昧な表現になりがちです。それを防ぐには、データパターンをマトリクスで用意しておくと良いでしょう。分かりやすいマトリクスがあれば、開発やテストでの仕様勘違いを最小限に防ぐことが出来ます。
・３．要件とシステムのバランス
機能詳細を書くには、要件とシステムのバランス取りが重要です。
例えばあまりにシステム寄りの目線で仕様書を書くと、ユーザーが読んでも理解出来なくなりますが、かと言って要件目線にし過ぎると、曖昧な記述になりがちです。ユーザーと開発者、どちらが読んでも理解しやすいバランスを見つけることが必要です。
⑧Ｉ／Ｏ仕様
プログラムを動かすために必要なインプット・アウトプット情報をここに記載しましょう。ファイルの入力・出力があるならそのファイルの内容や、関連する機能の仕様書のリンクなどを記載しておくと、後で読みやすいドキュメントになります。
またその他にも、使用するＤＢ一覧なども書いておくと、後々データの流れを把握しやすくなるのでオススメです。
⑨許諾事項
ドキュメントの最後には、許諾事項や免責事項を書いておきましょう。具体的には不正なオペレーションや動作環境外のOSでの利用、外部ツールによるウイルスやファイアウォールなどによる悪影響を受けた場合は、動作保証を出来ないという旨の記述です。
業務システム開発は、多額のお金が動く大きなプロジェクトですので、トラブル時に最小限の影響で済むよう、こうした注意書きが重要になります。
場合によっては補足資料を
MicroSoftのOficce Wordは優れた文書管理ソフトですが、それ専用に特化しているため、表管理など苦手な分野がないわけではありません。
そんな時はWordの１ファイルだけで全てを表そうとするのではなく、積極的に補足資料を作成しましょう。データパターンが膨大になるならExcelを、システムイメージを図で表したいのであればPDFを、それぞれ作成すれば良いのです。
詳細設計は、単にシステム内容を解説すれば良い、というものではありません。システム全体の流れを把握し、ユーザーと設計者の要件を分かりやすく記すことが何よりも大切なのです。
今回記載したフォーマットはあくまで一例ですので、プロジェクトに合わせた理想的な仕様書を作成してみましょう。
