初めてプロジェクトへ参加される方向け、ＩＴ関連ドキュメント作成の基本

システム開発ドキュメントとは

システム開発プロジェクトでは、プログラムやシステムそのものだけではなく、さまざまなドキュメントが作成されます。
要件定義書、設計書、テスト仕様書、操作マニュアル、運用手順書など、その種類は多岐にわたります。
これらのドキュメントは、単に作業の記録として残すものではありません。
「何を作るのか」「どのように作るのか」「正しく作られたのか」「完成後にどのように利用・運用するのか」を関係者間で共有するための重要な成果物です。

システム開発におけるドキュメントの役割

システム開発では、顧客、プロジェクトマネージャー、システムエンジニア、プログラマー、インフラ担当者、テスト担当者など、多くの人が関わります。
それぞれの立場によって、システムに対する関心や必要な情報は異なります。
また、段階（工程）ごとにも必要な情報が異なります。
そこで、それぞれの情報をドキュメントとして整理し、プロジェクト関係者の共通認識を作ることが重要になります。

システム開発プロジェクトのドキュメント体系

工程	主なドキュメント
企画	ＲＦＰ（提案依頼書・ユーザー作成）、プロジェクト企画書（提案書・ベンダー作成）
計画	プロジェクト計画書、プロジェクト体制図、スケジュール
要件定義	要件定義書、業務フロー、画面定義書、帳票定義書
基本設計	システム構成図、基本設計書
詳細設計	詳細設計書、機能仕様書、処理フロー
開発	開発環境構築手順書、コーディング規約
テスト	テスト計画書、テスト仕様書
リリース	移行計画書、リリース手順書
運用・保守	運用設計書、運用手順書、保守手順書

詳細は、下記に記載してあります。

企画に関するドキュメント

ユーザーがシステム要件を取りまとめＲＦＰを作成します。
もしくは、コンサル会社へ経営課題を提示しＲＦＰを作成依頼することもあります。
ＲＦＰをもとに数社のベンダーへ提案依頼を行い、各ベンダーから提案書を受領しベンダーを選定します。

• ＲＦＰ（提案依頼書）　　→　ユーザー
• プロジェクト提案書（企画書）　→　ベンダー

プロジェクト計画に関するドキュメント

プロジェクトの開始段階に、プロジェクト・システム開発をどのように進めるのかを整理します。

• プロジェクト計画書
  • プロジェクトの目的や対象範囲、体制、スケジュール、成果物などを整理した資料です。
  • プロジェクト開始時に関係者が同じ方向を向くための基本的な資料となります。
• プロジェクト体制図
• スケジュール
• WBS
  • WBS（Work Breakdown Structure）は、プロジェクトで実施する作業を細かく分解して整理したものです。
  • 作業内容や担当者、期限などを整理することで、プロジェクト全体の進捗を管理しやすくします。
• 課題管理表
• リスク管理表
• 進捗管理資料
• コミュニケーション計画書

要件定義に関するドキュメント

要件定義では、「システムで何を実現するのか」を明確にします。

• 要件定義書
  • システムに求められる機能や性能、業務上の条件などを整理した重要なドキュメントです。
  • 要件定義は、その後の設計や開発の基準となるため、特に重要な工程です。
• 業務要件一覧
• 機能要件一覧
• 非機能要件一覧
• 業務フロー
• 画面要件
• 帳票要件
• 外部インターフェース要件

基本設計に関するドキュメント

要件定義で整理した内容をもとに、システムをどのような構成・機能で実現するのかを決めます。

• 基本設計書
• システム構成図
  • サーバーやネットワーク、データベース、外部サービスなど、システムを構成する要素とその関係を図で表します。
  • システム全体を把握するための重要な資料です。
• 画面設計書
  • システムにどのような画面を用意するのか、画面上にどのような項目を配置するのかなどを整理します。
  • 画面イメージや画面遷移図などを利用して表現することもあります。
• 帳票設計書
• データベース設計書
• 外部インターフェース設計書
• 権限設計書

詳細設計に関するドキュメント

基本設計をさらに具体化し、開発者がプログラムを実装できるレベルまで設計内容を落とし込みます。

• 詳細設計書
• 機能仕様書
• 処理フロー
• シーケンス図
• クラス設計
• API仕様書
• データベース詳細設計書
• バッチ設計書

開発・プログラミングに関するドキュメント

設計書をもとにプログラムを実装するとともに、開発環境やコーディングに関する情報も管理します。

• 開発環境構築手順書
• コーディング規約
• ソースコード管理ルール
• 共通部品仕様書
• 設定ファイル一覧
• 開発手順書

テストに関するドキュメント

開発したシステムが要件や設計どおりに動作するかを確認するため、テスト工程ではさまざまなドキュメントを作成します。

• テスト計画書
• テスト仕様書
• テストケース
• テスト結果報告書
• 不具合管理表
• 総合テスト報告書
• 受入テスト資料

リリースに関するドキュメント

開発・テストが完了したら、システムを本番環境へリリースします。
特に本番環境へのリリースでは、作業ミスがシステム障害につながる可能性があります。
そのため、作業内容を手順書として明確にし、作業前後の確認項目をチェックリストなどで管理することが重要です。

• リリース手順書
• 移行計画書
• 移行手順書
• リリースチェックリスト
• 切り戻し手順書
• リリース結果報告書

運用・保守設計に関するドキュメント（開発時に設計）

本番稼働後には、監視、バックアップ、障害対応、定期メンテナンス、ユーザー管理などの運用作業が発生します。
システムを安定して運用するために作成します。

• 運用設計書
• 運用手順書
• 保守手順書
• 障害対応手順書
• バックアップ・リストア手順書
• 監視設計書
• 定期作業手順書
• システム構成資料
• FAQ
• 問い合わせ対応手順

システム開発ドキュメント作成方法

システム開発では、プログラムを作ることだけが重要なのではありません。
「何を作るのか」「どのような仕組みにするのか」「どのようにテストするのか」を明確に記録した開発ドキュメントも重要な成果物です。
ドキュメントが適切に作成されていれば、プロジェクトメンバー間で認識を共有できるだけでなく、後から仕様を確認したり、保守・改修を行ったりするときにも役立ちます。

ドキュメントを作成するときのポイント

• 目的を明確にする
  • 目的が曖昧なまま作成すると、必要以上に情報を詰め込んだ資料になってしまいます。
• 誰が読むのかを考える
  • ドキュメントの読み手によって、記載する内容や表現を変える必要があります。
• 図や表を活用する
  • 文章だけで説明すると、どうしても分かりにくくなります。
  • 特にシステム全体の構成や処理の流れは、文章よりも図にしたほうが理解しやすい場合があります。
• 用語を統一する
  • ドキュメント内で同じものを複数の名前で呼ばないことも重要です。
  • プロジェクト内で用語を統一し、必要であれば用語集を作成します。
• 変更履歴を残す
  • システム開発では、途中で仕様変更が発生することがあります。
  • ドキュメントには、版数・更新日・更新内容・更新者のような変更履歴を残しておくと便利です。

「作ること」より「更新すること」が重要

開発ドキュメントでは、作成することだけに注目しがちです。
しかし、実際のプロジェクトではドキュメントを最新状態に保つことが非常に重要です。
仕様変更 → プログラム修正 → ドキュメント更新という流れをプロジェクトのルールとして決めておきます。

保守・運用用ドキュメント

保守・運用のドキュメント作成は、システムの安定稼働と属人化の解消に不可欠です。
具体的には、「システム構成図」「運用手順書」「障害対応マニュアル」「問い合わせ対応記録」の4つを優先して整備しましょう。
これらを適切に残すことで、トラブル時の初動対応を迅速化できます。

保守・運用ドキュメントの必須項目と構成

システム構成図（全体像の可視化）

• 物理・ネットワーク構成図:
  • サーバー、ネットワーク機器、接続関係を図示します。
• 論理構成図:
  • OS、ミドルウェア、データベース、連携APIなどのバージョン情報。

運用手順書（業務の標準化）

• 日常・定期作業:
  • 日次点検、バックアップ取得、ログ確認、パッチ適用などの手順。
• スケジュール:
  • 実行する時間帯や頻度（日次、週次、月次）を明記。
• チェックリスト:
  • 作業漏れを防ぐための実績記録欄。

障害対応マニュアル（初動対応の迅速化）

• 監視アラート一覧:
  • 検知されるアラートの種類と、それぞれの重要度（レベル）。
• 初動対応フロー:
  • アラート発生時の確認手順、暫定復旧手順。
• エスカレーション先（連絡網）:
  • 担当者、ベンダー、顧客への連絡基準と連絡先リスト

問い合わせ対応記録（知見の資産化）

• FAQ/Q&A:
  • ユーザーや関係部署からよくある質問と回答、操作手順。
• トラブルシューティング:
  • 過去の障害やトラブル事例と、その解決策（ナレッジベース）。

ドキュメント運用のポイント

• 作成の基準:
  • 非技術者や新任担当者でも理解できるレベルの具体性を持たせる。
• 保守・更新ルール:
  • システム変更時や障害発生時にドキュメントを必ず更新するルールを定める。

保守・運用ドキュメント作成方法

保守・運用ドキュメントの作成は、「誰が読んでも迷わず作業できること」と「常に最新の状態に保つこと」が最大の目的です。
属人化を防ぎ、障害時の初動対応を迅速化するため、システムの全体像、日々の定型業務、緊急時の対応手順を明確に文書化します。

ドキュメント作成時のポイント

• 5W1Hと具体的数値を意識する：
  • 「確認する」「しばらく待つ」といった曖昧な表現を避け、「何を使って」「どのようなコマンドで」「何分待つか」を明記します。
• 図やスクリーンショットを活用する：
  • 文字の羅列よりも、実際の画面キャプチャやフローチャートを多用することで、視認性が上がりミスを防げます。
• 完璧を目指さずスモールスタートする：
  • 最初から完璧なものを作ろうとすると更新が滞ります。まずは要点だけをまとめ、運用しながら随時ブラッシュアップしていく姿勢が重要です。
• 実際のシステムと資料を一致させる：
  • システムを変更したときには、設計書や手順書も合わせて更新します。

形骸化を防ぐための運用ルール

• 更新のトリガーと担当者を決める：
  • システムの改修やアップデート時、あるいは「半年に1回」など定期的な見直しサイクルと担当者をあらかじめ設定します。
• 一元管理とアクセスのしやすさ：
  • ナレッジ共有ツールなどに集約し、「どこにあるか分からない」という状態を防ぎます。