目次
システム開発におけるドキュメントの基本
システム開発のドキュメントとは、プロジェクトの各工程で作成される、システムの仕様や設計、操作方法などを記録した文書のことです。ExcelやWord、PDF、専用ツールで作成されたデジタル文書も含まれます。
ドキュメントが果たす3つの役割
1. コミュニケーションツール
発注者と開発会社、開発チーム内での認識を合わせる共通言語として機能します。口頭での説明だけでは記憶が曖昧になり、人によって解釈が異なるリスクがあります。
2. 開発の設計図
建築の設計図と同様、システムをどう作るかの指針となります。設計書があることで、複数のエンジニアが一貫性を持って開発を進められます。
3. 保守・運用の資産
システムは作って終わりではなく、運用・保守が続きます。担当者が変わっても、ドキュメントがあれば継続的にシステムを維持・改善できます。
ドキュメント不足で起こるトラブル
「言った・言わない」の水掛け論
要件定義書がなく口頭で進めた結果、納品時に「この機能は含まれていると思っていた」という争いになり、追加費用や納期遅延が発生します。
運用開始後に誰も操作できない
操作マニュアルがないため、実際に使う社員が操作方法を理解できず、結局使われないシステムになってしまいます。
担当者の退職でブラックボックス化
開発経緯を知る担当者が退職し、設計書も残っていないため、システムの改修や不具合対応ができなくなるケースです。最悪の場合、一から作り直しになります。
中小企業が押さえるべきポイント
完璧を目指しすぎない
大企業のような詳細なドキュメントは、工数ばかりかかって本末転倒です。最低限、後から見返したときに内容が理解できる程度の記録を残すことを目標にしましょう。
開発会社との役割分担を明確にする
どのドキュメントを誰が作成するのか、プロジェクト開始時に明確にしておくことが重要です。納品物として何を受け取るのかも、契約前に確認しましょう。
更新のルールを決めておく
システム改修時にドキュメントも必ず更新するルールを設けないと、実際のシステムとドキュメントの内容が乖離してしまいます。
【工程別】システム開発で必要なドキュメント一覧
システム開発は複数の工程に分かれており、それぞれの段階で必要なドキュメントが異なります。工程ごとに整理して解説します。
企画・要件定義フェーズ
プロジェクトの最初の段階では、「何を作るか」を明確にするドキュメントが必要です。
要件定義書
システムに求める機能や性能を具体的に記載した、プロジェクトの土台となる最重要文書です。この文書の質が、プロジェクト全体の成否を左右します。
記載内容:
- 業務フローと課題
- 必要な機能（機能要件）
- システムの性能や制約（非機能要件）
- 画面イメージやレイアウト
- 外部システムとの連携要件
プロジェクト計画書
プロジェクト全体の目的、スコープ、スケジュール、予算、体制などをまとめた文書です。関係者全員が同じ方向を向くための基準となります。
設計フェーズ
要件定義が固まったら、「どう作るか」を詳細に設計します。
基本設計書（外部設計書）
システムの外側から見た設計、つまりユーザーから見える部分の設計を記載します。発注者も内容を確認し、承認する必要があります。
記載内容:
- 画面設計書（画面レイアウト、項目定義、遷移図）
- 帳票設計書（出力される帳票のレイアウトと項目）
- データベース設計書（テーブル定義、ER図）
- 外部インターフェース設計書（他システムとの連携仕様）
詳細設計書（内部設計書）
システムの内部構造、つまりプログラムの詳細な処理内容を記載した文書です。主に開発者向けの技術文書で、この設計書を元に実際のプログラミングが行われます。
開発・テストフェーズ
実際にシステムを構築し、品質を検証する段階で必要なドキュメントです。
ソースコード
プログラムの実体であるソースコードも、重要なドキュメントの一つです。適切なコメントが記載され、可読性が高いコードは、それ自体が優れた技術文書となります。
テスト仕様書（テストケース）
具体的なテスト項目、テスト手順、期待される結果を詳細に記載した文書です。この文書に基づいてテストを実行することで、漏れのない検証が可能になります。
テストの種類別に作成されます:
- 単体テスト仕様書（個々のプログラムの動作確認）
- 結合テスト仕様書（複数のプログラムを組み合わせた動作確認）
- システムテスト仕様書（システム全体の動作確認）
テスト結果報告書
テストの実施結果、発見された不具合、対応状況などをまとめた文書です。システムの品質を客観的に示す証拠となります。
納品・運用フェーズ
システムを実際に使い始める段階と、その後の運用・保守で必要なドキュメントです。
操作マニュアル（ユーザーマニュアル）
システムを実際に使う担当者向けの手引書です。専門知識がない人でも操作できるよう、画面キャプチャを多用し、分かりやすく記載する必要があります。
記載内容:
- ログイン方法
- 各機能の操作手順（画面キャプチャ付き）
- よくある操作のQ&A
- エラーメッセージと対処方法
運用マニュアル
システム管理者向けのマニュアルで、日常的な運用業務の手順を記載します。
記載内容:
- システムの起動・停止手順
- バックアップ手順
- ログの確認方法
- 障害発生時の一次対応
保守マニュアル
システムの改修や不具合対応を行う際に必要な技術情報をまとめた文書です。開発会社以外の技術者が保守を行う場合に特に重要です。
主要ドキュメントの作成ポイント
特に重要なドキュメントについて、具体的な作成ポイントを解説します。
要件定義書：プロジェクトの土台
要件定義書は、プロジェクトの成否を決める最も重要なドキュメントです。ここでの認識合わせが不十分だと、後工程で大きな手戻りが発生します。
記載すべき項目
1. プロジェクトの背景と目的
なぜこのシステムが必要なのか、どんな課題を解決したいのかを明確に記載します。開発会社が背景を理解することで、より適切な提案が期待できます。
2. 機能要件
システムに必要な機能を具体的にリストアップします。「顧客管理ができる」だけでなく、「顧客情報の登録・編集・削除・検索ができる」「顧客ごとの取引履歴を時系列で表示できる」など、詳細に記載します。
3. 非機能要件
機能以外の要件も重要です:
- 性能要件（応答時間、同時アクセス数など）
- セキュリティ要件（アクセス制御、データ暗号化など）
- 可用性要件（稼働時間、バックアップ頻度など）
認識合わせのコツ
曖昧な表現を避ける
「使いやすい画面」「高速な処理」といった主観的な表現ではなく、「3クリック以内で目的の機能にたどり着ける」「検索結果を3秒以内に表示する」など、具体的で測定可能な表現を使いましょう。
画面イメージを共有する
文章だけでは伝わりにくい部分は、手書きのスケッチでも構わないので画面イメージを添付します。PowerPointやExcelで簡単なモックアップを作成するのも効果的です。
優先順位をつける
すべての要件が同じ重要度ではありません。「必須」「あれば望ましい」「将来的に検討」など、優先順位を明記することで、予算や納期の制約がある場合の調整がしやすくなります。
設計書：システムの設計図
設計書は、要件定義で決めた「何を作るか」を「どう作るか」に落とし込む文書です。
基本設計書の作成ポイント
画面設計は利用者目線で
画面設計書では、単に項目を並べるだけでなく、利用者の操作の流れを意識したレイアウトにします。入力項目が多い場合は、グループ化や段階的な入力など、使いやすさを考慮します。
画面設計書に含める情報:
- 画面ID・画面名
- 表示項目（項目名、データ型、桁数、必須/任意）
- ボタンとその動作
- 入力チェックのルール
- 画面遷移
外部連携は詳細に定義
他のシステムとデータをやり取りする部分は、トラブルが起きやすいポイントです。データ形式（JSON、CSV、XMLなど）、項目定義、通信方式、エラー処理などを詳細に定義します。
詳細設計書の作成ポイント
複雑な処理は図解する
条件分岐が多い処理や、複数のテーブルを参照する処理など、文章だけでは分かりにくい部分は、フローチャートやシーケンス図を使って視覚化します。
例外処理を明確にする
正常系の処理だけでなく、エラーが発生した場合の処理も詳細に設計します。「どんなエラーが起こりうるか」「それをどう検知するか」「ユーザーにどう伝えるか」を明確にします。
設計書のレビューポイント
発注者側が設計書をレビューする際は、以下の点を確認しましょう:
- 要件定義書の内容が漏れなく反映されているか
- 画面や帳票のイメージが業務に合っているか
- 不明な点や曖昧な表現がないか
技術的な詳細が分からなくても、業務の観点から「これで実際に使えるか」を判断することが重要です。
テスト関連ドキュメント：品質を担保する記録
テスト仕様書の作成ポイント
網羅的なテストケースを設計する
機能が正しく動作することだけでなく、異常系のテストも重要です:
- 正常系：想定通りの入力で正しく動作するか
- 準正常系：許容範囲内の変則的な入力で適切に動作するか
- 異常系：不正な入力や想定外の操作でエラー処理が正しく動作するか
境界値テストを忘れずに
数値入力や文字数制限がある項目では、境界値（最小値、最大値、その前後）でのテストが重要です。例えば、1〜100の範囲で入力できる項目なら、0、1、100、101でテストします。
期待結果を明記する
各テストケースで「何が起これば正しいのか」を明確に記載します。「エラーが表示される」ではなく、「『顧客名は必須です』というエラーメッセージが赤字で表示される」のように具体的に記載します。
テスト結果報告書の作成ポイント
実施状況を定量的に示す
テスト項目数、実施済み項目数、合格/不合格の件数などを数値で示します。全体の進捗状況が一目で分かるようにします。
不具合の重要度を分類する
発見された不具合は、影響度に応じて分類します:
- 致命的：システムが停止する、データが破損する
- 重大：主要機能が使えない、業務に大きな支障がある
- 中程度：一部機能に問題があるが回避策がある
- 軽微：表示の乱れなど、業務への影響が小さい
運用マニュアル・操作マニュアル：利用者向けの手引き
マニュアルは、システムを実際に使う人のための文書です。技術的な正確さよりも、分かりやすさを優先します。
操作マニュアルの作成ポイント
画面キャプチャを積極的に使う
文章だけで説明するよりも、実際の画面キャプチャを使った方が圧倒的に分かりやすくなります。重要な部分は赤枠や矢印で強調しましょう。
業務の流れに沿った構成にする
システムの機能別ではなく、実際の業務の流れに沿って説明することで、利用者が必要な情報を見つけやすくなります。
例:
- ×「顧客管理機能」「案件管理機能」…（システム視点）
- ○「新規顧客の登録手順」「見積書の作成手順」…（業務視点）
初心者でも理解できる表現を使う
専門用語や略語は避け、平易な言葉で説明します。どうしても専門用語を使う場合は、初出時に説明を加えます。
よくある質問（FAQ）を設ける
実際に運用を始めると、同じような質問が繰り返されます。事前によくある質問とその回答をまとめておくことで、問い合わせ対応の負担を軽減できます。
納品時のドキュメント管理
システム開発が完了し、納品という段階で「必要なドキュメントが揃っていない」「内容が不十分で使えない」といったトラブルが発生することは珍しくありません。
納品物として求められるドキュメント
契約時に納品ドキュメントの範囲を明確にしておくことが、トラブル防止の第一歩です。
必須の納品ドキュメント
- ソースコード一式
- 要件定義書
- 基本設計書・詳細設計書
- データベース設計書
- 操作マニュアル
- 運用マニュアル
- テスト仕様書・結果報告書
プロジェクトによって必要なドキュメント
- API仕様書（外部システムとの連携がある場合）
- インフラ構成図
- セキュリティ設計書
- 移行手順書（既存システムからの移行がある場合）
中小企業の場合、すべてのドキュメントを完璧に揃えることが難しいケースもあります。その場合は、「運用に最低限必要なもの」を優先的に整備し、予算や期間の制約の中で優先順位をつけることが現実的です。
納品前の確認ポイント
ドキュメントの完成度チェック
記載内容の網羅性
契約時に合意した範囲のドキュメントがすべて揃っているか、目次や構成を確認します。特に設計書は、要件定義書で定義した機能がすべて反映されているかをチェックしましょう。
実際のシステムとの整合性
ドキュメントに記載されている内容と、実際に動作するシステムが一致しているかを確認します。開発途中で仕様変更があった場合、ドキュメントが更新されていないケースがあります。
第三者が理解できる内容か
担当者が退職したり、別の開発会社に保守を依頼したりする場合を想定し、ドキュメントだけで理解できる内容になっているかを確認します。
マニュアルの実用性チェック
実際の業務フローに沿っているか
操作マニュアルが、実際の業務の流れに沿った構成になっているかを確認します。実際にシステムを使う予定の従業員に読んでもらい、フィードバックを得ることが有効です。
画面キャプチャは最新か
マニュアルに掲載されている画面キャプチャが、納品されるシステムの最終版と一致しているかを確認します。
受け取り時の確認事項
ファイル形式と編集可能性の確認
設計書やマニュアルが、将来的に自社で修正できる形式（Word、Excel、PowerPointなど）で提供されているかを確認します。PDFのみの納品では、後から修正が困難です。
保存場所と管理方法の決定
納品されたドキュメントを、誰がアクセスできるようにするかを決定します。機密情報を含む設計書は限定的に、操作マニュアルは広く共有するなど、文書の種類によって管理方法を変えます。
引き継ぎとレクチャーの実施
ドキュメントの構成、重要なポイント、更新が必要になる箇所などについて、開発会社から直接説明を受けます。この機会に質問事項をまとめて確認しましょう。
納品後の整理方法
ドキュメントの分類と整理
ドキュメントを「エンドユーザー向け」「システム管理者向け」「開発者向け」に分類します。それぞれの役割に必要な文書だけをまとめることで、必要な情報にすぐアクセスできます。
バージョン管理のルール作り
ドキュメントのファイル名に、バージョン番号や更新日を含めるルールを作ります。例:「操作マニュアル_v1.0_20240315.docx」のように統一することで、最新版の識別が容易になります。
各ドキュメントの冒頭に更新履歴を記載するセクションを設け、「いつ・誰が・何を変更したか」を記録します。
定期的な見直しの仕組み
半年に一度、年に一度など、定期的にドキュメントの内容を見直す機会を設けます。システムの改修や運用方法の変更があった際に、ドキュメントも更新する習慣をつけます。
ドキュメント管理でよくある失敗と対策
システム開発のドキュメント管理では、多くの企業が似たような課題に直面します。よくある失敗パターンとその対策を紹介します。
ドキュメントが散らかり、最新版が分からない
よくある失敗
複数のメンバーがそれぞれの場所にドキュメントを保存した結果、同じ文書の異なるバージョンが社内の複数の場所に散在してしまうケースです。
- 各担当者のローカルPC、共有フォルダ、メール添付など、保存場所がバラバラ
- 「最終版」「最終版_修正」「最終版_修正2」のようなファイル名が乱立
- どれが正式な最新版なのか、誰も確信を持てない状態
効果的な対策
一元管理の場所を決める
ドキュメントの「正式な保管場所」を一つに決め、全員がその場所を参照するルールを徹底します。Google Drive、SharePoint、Notionなどのクラウドサービスを活用すれば、常に最新版にアクセスできます。
編集権限を明確にする
誰がドキュメントを編集できるかを明確にします。多くの人が自由に編集できると混乱するため、編集者は限定し、閲覧は広く許可するという方針が有効です。
バージョン管理機能を活用する
クラウドサービスの自動バージョン管理機能を使えば、ファイル名に「最終版」などと付ける必要がなくなります。変更履歴も自動的に記録されるため、過去の状態に戻すことも可能です。
作成に時間がかかりすぎて開発が遅れる
よくある失敗
ドキュメント作成に完璧を求めすぎて、本来の開発作業が進まなくなってしまうケースです。
効果的な対策
必要最低限のドキュメントに絞る
すべてのドキュメントを完璧に作る必要はありません。プロジェクトの規模やリスクに応じて、本当に必要なドキュメントだけを作成します。
例えば、小規模なシステムであれば:
- 詳細設計書は省略し、基本設計書とソースコードのコメントで代用
- 操作マニュアルは最小限にし、実際の操作レクチャーで補完
- テスト仕様書は主要な機能のみに絞る
テンプレートを活用する
ゼロから作るのではなく、過去のプロジェクトで使ったドキュメントをテンプレート化します。構成や表現を流用することで、作成時間を大幅に短縮できます。
AIツールを活用する
ChatGPTなどのAIツールを活用すれば、ドキュメントの下書き作成、文章の校正、図表の説明文作成などを効率化できます。
形式的に作っただけで誰も使わない
よくある失敗
「ドキュメントを作ること」が目的化してしまい、実際には誰も参照しない文書が大量に作られてしまうケースです。
効果的な対策
利用者の視点で作成する
ドキュメントを実際に使う人が誰なのかを明確にし、その人たちの知識レベルや業務内容に合わせた内容にします。
- エンドユーザー向け：専門用語を避け、画面キャプチャを多用
- システム管理者向け：トラブル対応や日常的なメンテナンス手順を重視
- 開発者向け：技術的な詳細や設計の意図を記載
実際の業務シーンを想定する
「この文書はどんなときに、誰が、何のために使うのか」を明確にします。利用シーンが明確でないドキュメントは、結局使われません。
フィードバックループを作る
ドキュメントを作成したら、実際の利用者に使ってもらい、フィードバックを収集します。「分かりにくかった点」「不足していた情報」を反映し、継続的に改善します。
属人化してしまい、担当者不在時に困る
よくある失敗
特定の担当者だけがシステムやドキュメントの詳細を把握しており、その人がいないと何もできなくなってしまうケースです。
効果的な対策
ドキュメントの所在を明確にする
「どこに何のドキュメントがあるか」を示す索引やマップを作成します。新しいメンバーが参加したときに、この索引を見れば必要な情報にたどり着けるようにします。
定期的な情報共有の場を設ける
月に一度など、定期的にシステムに関する情報共有の場を設けます。担当者が他のメンバーに、システムの仕組みやドキュメントの管理方法を説明する機会を作ります。
複数人でレビューする文化を作る
ドキュメントの作成や更新を一人で完結させず、必ず別の人がレビューする仕組みを作ります。レビューを通じて、複数の人が内容を理解する機会になります。
中小企業がシステム開発を成功させるために
システム開発におけるドキュメントの重要性を理解したうえで、中小企業が成功するための総合的なポイントをお伝えします。
自社に合ったドキュメント管理の仕組みを作る
大企業向けの複雑なドキュメント管理システムは、中小企業にとっては過剰な場合があります。自社の規模や業務の実態に合った、「ちょうどいい」仕組みを作ることが重要です。
身の丈に合ったツール選び
高機能なドキュメント管理システムを導入しても、使いこなせなければ意味がありません。まずは、すでに使い慣れているツールから始めることをお勧めします。
- Google Workspace：中小企業に広く普及しており、バージョン管理や共同編集が容易
- Microsoft 365：WordやExcelに慣れている企業に最適
- Notion：柔軟性が高く、ドキュメント管理とタスク管理を統合できる
重要なのは、全員が使えるツールを選ぶことです。
運用ルールはシンプルに
複雑なルールは守られません。ドキュメント管理のルールは、以下のように最小限にシンプルに保ちます。
- 保存場所は一箇所：すべてのドキュメントは指定のフォルダに保存
- 命名規則を統一：「文書名_バージョン_日付」の形式で統一
- 更新時は履歴を記録：何を変更したかを簡潔に記録
段階的に改善していく
最初から完璧な仕組みを作ろうとせず、小さく始めて段階的に改善していくアプローチが現実的です。
- 第1段階：保存場所を一箇所に集約する
- 第2段階：命名規則とフォルダ構成を整理する
- 第3段階：定期的な見直しの仕組みを導入する
開発会社との円滑なコミュニケーション
システム開発の成否は、開発会社との関係性に大きく左右されます。
曖昧な表現を避け、具体的に伝える
「使いやすいシステムにしてほしい」「きれいなデザインにしてほしい」といった抽象的な要望では、開発会社も対応に困ります。
- ×「使いやすいシステム」
- ○「入力項目は最小限にし、3ステップ以内で完了できるようにしてほしい」
このように、具体的な基準や数値で伝えることで、認識のズレを防げます。
定期的な進捗確認の場を設ける
開発が始まったら放置するのではなく、定期的に進捗を確認する場を設けます。週次や隔週でのミーティングを通じて、現在の進捗状況、発生している課題、仕様の確認などを行います。
疑問はすぐに質問する
分からないことをそのままにしておくと、後で大きな問題に発展します。技術的な内容で理解できない部分があれば、遠慮せずに質問しましょう。
DXやIT化に不安がある場合の進め方
「システム開発は必要だと分かっているが、何から始めればいいか分からない」という不安を抱える中小企業の経営者は少なくありません。
小さく始めて、徐々に拡大する
いきなり大規模なシステムを導入するのではなく、小さな範囲から始めて、成功体験を積み重ねるアプローチが有効です。
例えば:
- まずは特定の部署の業務だけをシステム化
- 効果を確認してから、他の部署にも展開
- 段階的に機能を追加していく
このステップを踏むことで、リスクを最小限に抑えながらIT化を進められます。
既製品とカスタム開発の使い分け
すべてをカスタム開発する必要はありません。既製品で対応できる部分は既製品を使い、どうしても自社の業務に合わない部分だけをカスタム開発する方法もあります。
ただし、SaaSが合わない企業も存在します。
- 業界特有の複雑な業務フローがある
- 既存システムとの連携が必要
- 独自の計算ロジックや承認フローがある
こうした企業には、必要な機能だけを実装した「ちょうどいい」カスタムシステムが最適です。
伴走してくれるパートナーを選ぶ
システム開発は、納品して終わりではありません。導入後の運用、改善、追加開発など、長期的な関係が続きます。
単にシステムを作るだけでなく、導入後も伴走してくれるパートナーを選ぶことが、中小企業のDX成功の鍵です。
- 操作レクチャーや社内展開の支援
- 運用開始後の改善提案
- 小さな修正や機能追加への柔軟な対応
- 長期的な視点でのIT戦略の相談
Harmonic Societyが大切にしている開発の考え方
私たちHarmonic Societyは、「テクノロジーが人を置き去りにしない社会をつくりたい」という想いから生まれました。
「ちょうどいい」を大切にする
大企業向けの高機能なシステムは、中小企業にとっては過剰です。かといって、簡易的すぎるツールでは業務に対応できません。
私たちが目指すのは、御社の業務に必要な機能だけを抽出した、最小構成のシステムです。無駄な機能がないため、使いやすく、覚えやすく、コストも抑えられます。
AI活用で短期間・低コストを実現
すべての開発プロセスにAIを活用することで、従来の開発費の1/3〜1/2程度、開発期間も1/10程度でのシステム構築を実現しています。
これは単なるコスト削減ではありません。中小企業でも手の届く価格で、質の高いシステムを提供することで、大企業との競争力格差を縮めたいという想いがあります。
導入後も見据えた支援
システムを作って納品して終わりではなく、実際に使えるようになるまでを支援します。
- 操作レクチャーで社員の皆様が使えるように
- 運用開始後の改善提案
- 小さな修正や機能追加への柔軟な対応
- 保守管理まで一気通貫でサポート
システム開発のドキュメント管理は、プロジェクトの成功に不可欠な要素です。本記事で紹介したポイントを参考に、自社に合ったドキュメント管理の仕組みを構築し、システム開発を成功に導いてください。
