システム開発の工程において、ドキュメント制作に要する時間は決して少なくありません。一方で、各開発工程で出力されるドキュメントについて、その必要性を疑問視している方も多いのはないでしょうか。
大量に作成したドキュメントもあまり利用されていない、更新が追いつかない、という状況もしばしば見かけるため、ドキュメントが軽視されてしまっている要因になっているのではないでしょうか。
本稿では、各種ドキュメントの種類や目的について改めてご紹介し、本来の役割についてご説明いたします。
システム開発に関するドキュメント
| ドキュメント名 | 作成のタイミング | 内容 |
|---|---|---|
| RFP (提案依頼書) |
システム開発検討時 (クライアントから提出) |
クライアントが開発を請け負うシステム会社に対し、開発を依頼するシステムの要件について明文化したもの。5W1H(目的、予算、納期、運用等)で明記するのが基本。 |
| 要件定義書 | 見積前または概算見積り後 | RFPの内容とクライアントの要望をヒアリングし、システムエンジニアが作成するもの。業務をシステム化する目的や要求、課題内容を整理した上で実現するための方法、作成する機能、大まかな見積を提示する。 |
| 基本設計書 | 設計段階 | 要件定義にもとづいて具体的な画面のレイアウトや入出力する帳票フォーマット、管理項目や実装したい機能などを使用するシーンと運用するシーンを想定しつつ設計していきます。 |
| 詳細設計書 | 設計段階 | システムの大枠を作った基本設計の内容をブレークダウン(細分化)し、その処理内容をプログラム化しやすい方法でまとめたもの。基本的にはシステム会社の内部的なドキュメントになるため、クライアント側でのレビューはありません。 |
| 単体テスト仕様書/成績書 | 設計段階/テスト段階 | 1つ1つのプログラムを単体で動かし、その共働を検証するためにテスト項目を記載した仕様書と、実際に単体テストを実行した際に記入する成績書。 |
| 結合テスト仕様書/成績書 | 設計段階/テスト段階 | 各プログラムを繋ぎ合わせて一つの機能として正しく動くかどうかを検証するための、テスト項目を記載した仕様書と、実際に結合テストを実行した際に記入する成績書。 |
| システムテスト仕様書/成績書 | 設計段階/運用開始前 | システムを総合的に操作して正しく動くかどうかを検証するための、テスト項目を記載した仕様書とシステムテストを実行した際に記入する成績書 |
会議や打ち合わせ時に関するドキュメント
| ドキュメント名 | 作成のタイミング | 内容 |
|---|---|---|
| 議事録 | 打合せ時 | 要件定義や各種ドキュメントのレビューなどの打合せ内容を議事録として作成したもの。通常はシステム会社が作成し、クライアント側がそれを承認する形式で作成されます。 |
| 課題管理表 | 打合せ時 | 打合せ時に洗い出した課題や問題点を一覧表としてまとめたものであり、対策や期日等も記載されています。議事録と一緒に管理されることが多く、打合せの冒頭では毎回、管理課題表を見て進捗を管理します。 |
スケジュールや開発工程に関するドキュメント
| ドキュメント名 | 作成のタイミング | 内容 |
|---|---|---|
| WBS(Work Breakdown Structure) | 要件定義後都度 | システム開発プロジェクト全体のタスクを洗い出し、その優先度や処理順、それぞれのスケジュールについて記載したものです。システム会社が作成し、近年ではクライアントと共有してお互いにタスクを確認し、進捗を管理するために用います。 |
| 開発工程表 | 要件定義後都度 | ＷBSよりも大まかな工程で作成されるスケジュール管理票です。設計、コーディング、テストなどプログラミング期間を中心に予定を記入し、定例会議などで実績を記したものと双方で確認します。 |
納品に関するドキュメント
| ドキュメント名 | 作成のタイミング | 内容 |
|---|---|---|
| 操作説明書 | テスト完了時/運用開始前 | 開発したシステムの操作マニュアルであり、画面ごとに入力するデータや手順、あるいは入出力する帳票等について記載します。個別のドキュメントとしては作成せず、システム画面上のヘルプファイルから操作説明書を呼び出せるようにする場合もあります。 |
| 運用マニュアル | テスト完了時/運用開始前 | 通常の運用業務の流れに沿って作成するマニュアルです。システム会社とクライアントの双方で協力しながら作成するのが一般的であり、クライアント独自に一連の運用業務ができるよう手順を記載します。 |
そのドキュメントは誰のためにある？
各ドキュメントの重要性を理会するために大切なことが「誰のためのドキュメントなのか？」を常に考えることです。システム開発で作成するドキュメントは形式的に作っているものではなく、それには必ず目的があります。その目的とは次のようなものです。
要件定義書
システム化する業務というのは抽象的なものなので、何をシステム化してどんな機能を実装するのかといった項目を明確にすることで、認識のずれを起こさないことが目的です。そのため要件定義書はクライアントのためだけでなく、システム会社自身のためのドキュメントと言えます。他にも開発方法や開発期間など抜け目なく各項目を記載し、重要な点についてはクライアント視点で記載することが大切です。
基本設計書
要件定義書で決定した事項はまだまだ抽象的なので、それを具体的な画面レイアウトや入出力する帳票フォーマットといった形で落とし込んでいきます。このドキュメントはクライアントのために作成するものでもあり、システム会社自身のために作成するものでもあります。何かを作るという工程では基本となる設計書が大切で、これは無形商材となるシステム開発では製造業でも同じことです。大まかな挙動をすり合わせて、システムとして必要な項目をクライアントと共に洗い出していきます。
詳細設計書
基本設計からさらにブレークダウンしたドキュメントであり、技術資料にもなるのでシステム会社の開発者向けのものです。ただしクライアントによって詳細設計書の提示を求めてくる場合もありますし、システム会社からクライアントに対して詳細設計書の説明をする場合もあります。
処理フロー定義や、エンティティの物理設計など開発者視点で作成されていることが多いですが、クライアントに提示する際や分かりやすい内容に置き換えることが大切です。
このように、「誰のためのドキュメントなのか？」を考えることによって各開発工程において作成してドキュメントの重要性に気付くことができます。ただし開発者によっては「プログラム設計書は都度更新が難しいから、ソースコードのコメントからドキュメント化する」という考え方を持っている場合もあります。これはこれで間違いではありません。
ドキュメントの作成・管理
各ドキュメントは、それを利用する人にとって閲覧性や可読性が高くなければなりません。また人によって解釈が変わることがないよう、完結に必要事項が記載されていることが望ましく、仕様や要件の変更は即座に反映されている必要があります。
また、ドキュメントの提供媒体や作成方法も変化しています。納品物や成果物として制作されるものも、現在ではPDFなど電子データで提供されることが多く、作成段階でも共同制作のスタイルをとるため、作成・更新・共有など制作フロー全体を網羅したツールやプラットフォームを利用することも多くなっています。
まとめ
いかがでしょうか？今回はシステム開発で用いる関連ドキュメントについてご紹介いたしました。分厚いバインダーを紐解くようなことは最近ではなくなりつつありますが、姿・形を変えてドキュメントとしての役割は現在でも生き続けています。
もちろん、ドキュメントを適切に作成・管理することは、システム開発の生産性を向上するばかりでなく、品質面や開発したソフトウェアの定着化や浸透にも貢献するため、非常に重要な役割を現在でも担っています。
