# インシデントレポート執筆 ## 定義 インシデントレポート（IR）執筆とは、インシデント対応後に**組織とコミュニティの学習を最大化することを目的として**、インシデントの経過・分析・教訓を文書化する行為である。[[ポストモーテム]] の書面化フェーズに該当するが、単なるテンプレート埋め込みではなく、読まれ語り継がれる文書を書くための技術・判断・文体のセットを指す。 核心命題（[[Laura Nolan]]、SREcon22 EMEA 2022）:「インシデントレビューの価値は**学習にあり、プロセスにあるのではない**」。多くの IR はテンプレートを機械的に埋める形式で書かれ、関係者以外に読まれないまま学習機会が失われる。(Source: [[@2022__SREcon22 EMEA__Ditch the Template - How to Write Incident Reports They Want To Read]]) ## テンプレート型 vs ナラティブ型 SRE Book テンプレート（Title / Date / Authors / Summary / Impact / Root Causes / Trigger / Resolution / Detection / Action Items / Lessons Learned / What went well/wrong / Where we got lucky / Timeline / Supporting information）はプロセスの遵守には有効だが、**ナラティブ（物語）を失わせる**という根本的な問題がある。 | 側面 | テンプレート型 | ナラティブ型 | |---|---|---| | **構造** | 定義済みセクションへの箇条書き記入 | 謎→調査の試行錯誤→解決の 3 部構成 | | **読者性** | 関係者以外はほぼ読まない | 関心あるエンジニアなら誰でも引き込まれる | | **学習の深さ** | 「何が起きたか」の事実記録 | 「その時点で何が見えていたか」の再現 | | **長期価値** | 形骸化しやすい | 年単位で語り継がれる知識になりうる | | **分析** | 「Lessons Learned」の箇条書きで終わりがち | 「モラル（教訓）」としてシステム論的洞察を示す | (Source: [[@2022__SREcon22 EMEA__Ditch the Template - How to Write Incident Reports They Want To Read]]) ## 良い IR の 4 軸 **1. ナラティブ重視（Focus on narrative, not metadata）** IR をストーリーとして書く。謎の発生（"what is happening?"）→試行錯誤の調査→犯人の発見と解決、という構成が読者を引き込む。調査中の不確実性や「まだ分かっていなかった」状態を率直に記述することがリアリティを生む。(Source: [[@2022__SREcon22 EMEA__Ditch the Template - How to Write Incident Reports They Want To Read]]) **2. 読者サポート（Supporting the Reader）** - すべてのエンジニアが読めるよう書く（専門知識を前提としない） - ジャーゴンとシステム名を説明する - **なぜ**そのシステムがそうなっているかを説明する - 簡潔な背景説明をナラティブに織り交ぜる - より詳細なドキュメントへリンクする **3. 視覚化（Be Visual）** 一枚の図は千の言葉に値する。アーキテクチャ図・グラフ・シーケンス図・タイムライン・スクリーンショット・トポロジー図を惜しまず使う。複雑なインシデントほど視覚表現が効果的。(Source: [[@2022__SREcon22 EMEA__Ditch the Template - How to Write Incident Reports They Want To Read]]) **4. 分析の共有（Don't be afraid of analysis）** 「IR がストーリーなら、分析はその教訓（モラル）」。技術的修正だけでなく、**システム運用の洞察**（なぜそのような状況が生まれるのか、どんな運用ゾーンが健全か等）まで踏み込むことで IR は長く語り継がれる文書になる。(Source: [[@2022__SREcon22 EMEA__Ditch the Template - How to Write Incident Reports They Want To Read]]) ## 文体の原則（Craft） | 原則 | 内容 | |---|---| | **印象的なタイトル** | 読者が後で参照できる記憶に残るタイトル（「Cascade of doom: JIT, and how a Postgres update led to 70% failure on a critical national service」） | | **シンプルで明確な言語** | 専門的手順も「通常であれば簡単なはずなのに」という文脈から始める | | **適度な文体** | 形式的すぎず、くだけすぎず | | **見出しで構造化** | テキストの壁を避ける | | **文のリズム** | 長短混在で単調さを避ける | | **時制の統一** | 過去か現在かを一貫させる | | **文化的比喩を避ける** | 国際読者を想定する | | **セールスピッチにしない** | 誠実・謙虚・正直が信頼を生む | (Source: [[@2022__SREcon22 EMEA__Ditch the Template - How to Write Incident Reports They Want To Read]]) ## 横断的知見 - **専門知識の継続的損失を IR が補う**: [[Laura Nolan]] はブログ記事（2023-03-31）で "expertise is critical to reliable operations" と述べ、IR は組織から常に失われ続ける専門知識を再構築する重要なツールだと主張する（Richard I. Cook 命題 13「人的専門知識は変化し続ける」への応答）。これは [[ポストモーテム]] の「長期的な知識ストア」「オンボーディング」機能の文書執筆レベルでの実装として位置づけられる。(Source: [[@2022__SREcon22 EMEA__Ditch the Template - How to Write Incident Reports They Want To Read]]) - **ポストモーテムで唯一必須のセクションは narrative description**: [[Lorin Hochstein]] は SREcon26 Americas で、ポストモーテムテンプレートの中で自身が本当に気にするのは「ナラティブ記述」セクションだけであると述べた。タイトルや概要は必要だが、学習価値は物語の中にある。時系列で書き、意味のある区切り(エピソード)に小見出しを付け、インシデント開始より前(数ヶ月〜数年前)から書き始めることが推奨された。Laura Nolan の「ナラティブ重視」と合流する知見。(Source: [[@2026__SREcon26Americas__The Power of Stories]]) ## 未解決の問い - ナラティブ型 IR とテンプレート型 IR で「読まれた率」「組織学習への貢献」を定量比較した研究はあるか。 - ナラティブ形式の IR は書くコストが高い（時間・スキルが必要）。テンプレートとの最適な折衷点はどこか。 - 公開 IR（GitLab・Cloudflare・Slack 等）で顕著なナラティブ品質は、外部向け透明性のインセンティブによるものか。社内 IR にナラティブ品質を維持するための組織的インセンティブ設計は何か。 - インシデントレビュー会議がアクションアイテム議論に占拠される問題(Hochstein が言及)に対して、ストーリーテリング専用セッション(Once Upon an Incident 形式)は現実的な解か? 両者を同じ会議に統合する方法はあるか? ## 関連 - [[ポストモーテム]] — IR 執筆が位置する上位プロセス - [[インシデント管理]] — IR 執筆が属するフェーズ（Learn） - [[人的要因]] — ローカル合理性を反映するナラティブが後知恵バイアスを減らす ## 出典 - [[@2022__SREcon22 EMEA__Ditch the Template - How to Write Incident Reports They Want To Read]] — [[Laura Nolan]]（[[Stanza Systems]]）、SREcon22 EMEA、2022-10-26 - [[@2026__SREcon26Americas__The Power of Stories]] — [[Lorin Hochstein]]（Airbnb）、SREcon26 Americas