システムやソフトウェア開発を進める上で、ドキュメントと呼ばれる様々な文書を作成します。
開発担当者の方は、日々ドキュメント作成に多くの工数を要していると感じられているのではないでしょうか。
一方で、近年は目まぐるしく変化する社会の流れに合わせ、開発効率とスピード感を重視したアジャイル型で進めるプロジェクトも増えており、ドキュメントの必要性を疑問視する声も聞かれるようになってきました。
本記事では、なぜドキュメントを作成するのか疑問を感じられているエンジニアの方や、そもそもドキュメントとはどのようなものなのかを知りたい初心者の方に向けて、ドキュメント作成の目的と重要性について解説していきます。
ドキュメント作成の目的
まず始めに、ドキュメント作成の目的について解説していきます。
ドキュメント作成の目的は、後述するドキュメントの種類によって違ってきますが、大きな括りとしては「コミュニケーションを円滑にするためのもの」であると言えます。
どのようなコミュニケーションを円滑にするのかという観点で３つに分類することができますので、それぞれ見ていきましょう。
１．開発側とクライアントのすり合わせ
システムやソフトウェアを開発するエンジニアとクライアントの間には、ITに関する知識量に差があることがほとんどなのではないでしょうか。
そのため、エンジニアが普段使い慣れているIT用語もクライアントにとっては耳慣れない言葉かもしれません。
両者が口頭のみでやりとりをすると「言った言わない」といったトラブルや、「言わなくてもやってくれると思っていた」などの認識齟齬が起こりやすくなります。
そもそも開発側とクライアントが共通の完成イメージを持つことができなければ、プロジェクトは失敗となるため、このようなトラブルを防止するためにも必ずドキュメントを作成し、予算・要件・デザイン・機能・納期などを明確にします。
２．プロジェクトメンバー間の意思疎通
多くの開発現場では、最初から最後までひとりが担当することはなく、開発規模に合わせて複数人がプロジェクトに関わります。
また、開発フェーズに合わせて適した技術者が担当することが一般的なので、工程をまたぐときに担当者が変わることになります。
工程移行する際に滞りなく引継ぎが行えるよう、また、開発途中で仕様変更が生じた際にも漏れなく情報共有できるよう、記録として残すためにドキュメントを作成します。
３．保守・運用の業務引継ぎ
システムやソフトウェアの完成後、実際に運用してみると、想定していなかったトラブルが起きたり、バグが見つかったりすることがあります。
このようなトラブルやバグは随時修正していく必要があり、該当するシステムがどのように構築され、どのようなテストを実施したのかといった経緯を把握しておかなければなりません。
ドキュメントがあれば、修正点をすばやく発見することができ、修正でどのような変更を行ったかを記録として残すことにより、保守・運用担当者が変更になる際にも引継ぎをスムーズに行うことができます。
ドキュメントの種類
一般的な「ドキュメント」が意味するものは記録物や文書ですが、システム開発におけるドキュメントは主に設計書や仕様書、マニュアルなどを指します。
仕様書と設計書の違いについて触れておくと、「仕様書」は完成までの制作工程を明確にしたもので、「設計書」は完成イメージを明確にするためのものになります。
ドキュメントは各工程ごとに作成するため、複数種類ありますが、今回はシステム開発における一般的なドキュメントについて解説いたします。
| 開発工程で作成される一般的なドキュメント一覧 | 作成のタイミング |
| RFP(提案依頼書) | 開発検討段階 |
| 要件定義書 | 見積もり前または概算見積もり後 |
| 基本設計 | 設計段階 |
| 詳細設計 | 設計段階 |
| テスト仕様書/報告書 | 設計段階/テスト段階 |
| 運用マニュアル | 運用テスト実施までに作成 |
RFP(提案依頼書)
RFPはRequest for Proposalの略称で提案依頼書とも呼ばれます。
RFPはクライアントが開発側に業務を委託するにあたり、具体的な提案を依頼するために作成するものであり、以下のような情報が記載されています。
- プロジェクトの概要
- システムの要件
- システムの評価基準
- システムの目的や概要
- 制約条件
- 開発の目的、目標、予算、スケジュール
- 提案を依頼したい範囲、役割分担、必須な機能、運用・保守、成果物
これらは5W1Hで明記するのが基本です。
RFPに対する開発側からの回答として、具体的な提案や正確な見積もり金額などが明記されます。
要件定義書
要件定義書はRFP(提案依頼書)の内容であるクライアントの要望を基に、システムが満たすべき性能や機能を明確にしたものになります。
要件定義書には以下のような情報が記載されています。
- システムの概要（目的・背景・課題・解決策）
- 業務要件（業務フロー）
- 機能要件（必要な機能）
- 非機能要件（セキュリティ・性能・運用）
- 実行計画（開発の計画）
要件定義書はクライアントの要求に応えるための羅針盤の役目を果たすものであり、基本設計や詳細設計のベースとなります。
「要件定義」と似た言葉で「要求定義」があり混同しやすいですが、要求定義書はクライアントの「要望・希望」を記載したものであり、要件定義は、クライアントの要望・希望を実現可能にするために「具体的な機能や要件」としてまとめたものになります。
基本設計
基本設計は、要件定義でまとめた内容を実現するためにシステムやソフトウェアに実装する機能を具体化したものです。
画面レイアウト、ボタンの配置、出力する帳票、データ処理設計、システムの連携方法などを記載します。
基本設計には以下のような情報が記載されています。
- 画面設計書
- 帳票設計書
- バッチ設計書
- データベース設計書
- 外部インターフェース設計書
詳細設計
詳細設計は基本設計の内容をさらに細分化し、エンジニアが実装しやすいように内部構造や仕様を示したものです。
詳細設計には以下のような情報が記載されています。
- クラス図
- シーケンス図
- ステートマシン図
基本設計は外から見たシステムの動きを記すのに対し、詳細設計はシステムの内部まで詳細に示すため、基本設計は「外部設計」詳細設計は「内部設計」とも呼ばれます。
基本設計はクライアント向けに作成しますので、難しいIT用語は使わず読みやすい記述を心掛けることが重要です。詳細設計はエンジニアに向けた指示書になりますので、IT専門用語が多い記述になります。
テスト仕様書/報告書
テスト仕様書は、テストをどのように実施するのかを記したものです。
テストは、単体テスト・結合テスト・総合テストと３つに分かれています。
単体テストではプログラムを単体で動かし、結合テストでは各プログラムをつなぎ合わせて、総合テストでは総合的に操作して正しく動くか検証します。
それぞれのテスト項目をまとめたものがテスト仕様書で、テスト結果がテスト報告書になります。
テスト仕様書には以下のような情報が記載されています。
- テスト条件
- テスト実施手順
- テスト期待結果
- テスト実施担当者
- テスト実施端末
- テスト実施日
- 判定結果
運用マニュアル
運用マニュアルは、クライアントが一連の運用ができるよう手順や説明を記載したものです。
運用マニュアルは主に次の3つの項目から構成されています。
- 業務マニュアル・・・システムの一連の流れについて可視化し、業務全体を把握するためのもの
- 操作マニュアル・・・実際にシステムを操作するために、具体的に手順が記載されたもの
- 障害対応マニュアル・・・障害発生時に迅速に対応できるよう備えたもの
マニュアルは業務に精通した担当者が作成することが多いですが、マニュアルを一番よく使うのは業務に詳しくない担当者です。
確認したい作業が検索しやすいことや、初心者目線でわかりやすい内容であることが求められます。
ドキュメントの重要性
これまで解説してきたように、ドキュメントは認識齟齬の防止 ・開発遅延の防止 ・運用の負担軽減など各フェーズで役割があります。
アジャイル開発においても、このようなメリットを享受するためにドキュメントを作成することをおすすめします。
むしろ効率を重視するアジャイル開発だからこそ、作成したほうが良いと言えるでしょう。
反対に、もしこれらのドキュメントが無い場合や、きちんと管理されていない場合、様々なトラブルが想定されます。
ドキュメントに関わるトラブル
ドキュメントに関わるトラブルとはどういったことが考えられるでしょうか。
要件定義書の内容があいまい
システムやソフトウェアは「機能」であり、直接目に見えるものではありません。
ですので、それがクライアントの要望に沿ったものになっているのか否かは、機能を可視化したドキュメントによって判断します。
要件定義書があいまいで分かりにくい場合は、設計者が本来の意図と異なる解釈をしてしまう可能性があり、手戻りの原因となります。
保守・運用に必要なドキュメントが残っていない
運用開始後にシステム障害や、致命的な不具合が発生したときに、誰が何をするというような役割分担や、手順が無い場合、復旧に遅れが出たり、責任の擦り付け合いになったりなどの二次トラブルが発生する可能性があります。
実装されているシステムの状態と設計書に乖離がある
リリースを急ぐあまり、設計・実装・テストに工数を優先的にかけてしまい、ドキュメント作成、更新に時間をとることができないということもよく耳にします。
しかし、機能拡張や改修を重ねると構造が複雑化していくため、すでに実装した機能にどのような意図があるのかといった情報を残すことは必要不可欠です。
ドキュメントが最新になっていない場合、調査に時間を必要以上に要してしまったり、影響範囲の特定ができなくなったりします。
まとめ
以上、ドキュメント作成の目的と重要性について解説してまいりました。
ドキュメント作成は工数もかかりますが、それに見合うメリットやドキュメントを作らなかった時のリスクがあることをおわかりいただけたのではないでしょうか。
弊社、株式会社QualityCubeはシステム、ソフトウェアの品質向上を使命として、様々な業界のプロジェクトをサポートさせていただいているIT品質コンサルタントであり、ドキュメントに関しても開発スピードを落とさず、効率よく作成できる方法をご紹介しております。
「ドキュメント作成のコツ」について知りたい方は、ぜひこちらのダウンロード資料をご活用ください。
より詳細な情報や、貴社の状況に合わせた具体的な提案が必要な場合は、お気軽にご相談ください。例えば、以下のような課題からお問い合わせを頂くケースが多くなってきております。
- システム開発で作成するドキュメントにおいて、定型のテンプレートがない
- ドキュメントがテンプレート化されていないため、項目をその都度考えて作成しなければならず効率が悪い
- ドキュメントがテンプレート化されていないため、ドキュメントの粒度や項目が人によって異なり、考慮漏れが発生している
- ドキュメントがテンプレート化されておらず定型でないため、レビューアへの負担が大きい。また、レビュー効率やレビュー精度の低下を招いている
