エンジニアリングドキュメント実践ガイド：README・手順書・Runbook・ADR・ポストモーテム

第1章：実務ドキュメントの全体像（目的別・成果物別マップ）

この章で学ぶこと

  • README / 手順書 / Runbook / ADR / 障害報告 / ポストモーテムの使い分け基準を理解する
  • 目的（理解 / 実行 / 判断）に応じて成果物を選ぶ
  • 成果物を「マップ」として整理する
  • 監査メモを、修正判断と変更不要判断の証跡として位置づける

この章の成果物（または判断基準）

本文

実務で起きがちな失敗は、成果物が混在すること（例: README に運用手順が埋もれる）。まず「何のための文書か」を固定する。

使い分け（最小）

  • README: 入口。何があり、どう動かすか
  • 手順書: 1回の作業を再現する
  • Runbook: 異常時を含む運用を回す
  • ADR: 判断の背景と選択肢を残す
  • 障害報告: 障害中から復旧直後に、確認できた事象・影響・タイムライン・対応状況を関係者へ説明する（障害報告テンプレ）
  • ポストモーテム: 復旧後に事実関係が安定してから、真因・背後要因・再発防止・検証を学習成果として残す（ポストモーテムテンプレ）
  • 監査メモ: 調査範囲、根拠、変更判断、変更不要判断を残す

障害報告はリアルタイムの状況共有と説明責任、ポストモーテムは復旧後の学習と再発防止を担う。障害報告を真因分析の完成まで待たせず、ポストモーテムを顧客・関係者への状況報告の代わりにしない。両者は同じ障害を扱っても別成果物であり、障害報告からポストモーテムと follow-up Issue / PR へ事実関係を引き継ぐ。

この章のゴールは「どの成果物を書くべきか」を説明できる状態にすること。

監査メモの位置づけ

他書籍レビュー、外部仕様確認、既存 Runbook の棚卸しでは、必ずしも本文変更が発生するとは限らない。変更しなかった判断も、あとから再確認できるように残す必要がある。

監査メモには、少なくとも次を記録する。

項目 目的
確認範囲 どの章、テンプレート、公開ページ、外部資料を見たかを示す
根拠 一次情報、実行ログ、PR、Issue、過去障害など判断材料を示す
判断 修正する、変更不要、別 Issue に分離する、のいずれかを明確にする
再確認条件 仕様変更、障害再発、Owner 変更など再確認のきっかけを示す

具体例（悪い例→良い例）

悪い例

README に以下を全部書く
- デプロイ手順
- 障害時の対応
- 意思決定の背景
（どこに何があるか分からない）

良い例

README は入口に絞る
- Quick Start
- 依存/権限
- 運用導線（Runbook へのリンク）
デプロイは手順書、障害対応は Runbook、状況と影響の説明は障害報告、
復旧後の学習と再発防止はポストモーテム、判断は ADR に分離

チェックリスト

  • 目的（理解 / 実行 / 判断）が明確
  • 成果物が混ざっていない
  • 入口（README）から導線がある
  • 変更判断と変更不要判断を残す場所がある

まとめ

  • 目的（理解 / 実行 / 判断）から成果物を選び、1つの文書に混在させない
  • README を入口にし、手順書 / Runbook / ADR / 障害報告 / ポストモーテムへ導線を用意する
  • 監査メモは「何を確認し、なぜ変更した / しなかったか」を残す成果物として扱う

次章への接続

Edit this page on GitHub