【例文付き】障害報告書の書き方・ポイントについてまとめてみた

文章を書く際のポイント

以下になります。

• 読み手が誰なのか意識をする
• 具体的な数値を交える
• 感情を排し、事実のみを書く

順番に詳しく書きます。

読み手が誰なのか意識をする

文章には必ず読む人がいます。

日記のような自分さえ意味が分かれば良い文章の場合や、
エンジニアの同僚に技術的な相談をする文章の場合や、
技術職ではない人に技術的なことを説明する文章の場合など、
挙げだすとキリがないと思います。

障害報告書の場合は、ユーザー(顧客)向けの事情の説明に用いられるなど、
多くの場合はエンジニアではない人(システムの内部構造を知らない人)向けの説明文となるので、
システム的な用語を一切使わないくらいの気持ちで書くのが良いと考えます。
※以下の表のような感じで言い換えるイメージです。

用語	言い換え
null	テキストボックスが空白の状態で登録した場合のデータ
404	該当するページが見つからない状態
500	システムに問題があってエラーになった

冗長であったり、細かなニュアンスを正確に言い表せないことに不安を覚えるかもしれませんが、
専門用語を使う方が相手に伝わらないのであれば、
そこの不安には目を瞑るべきです。

具体的に報告する

特に影響範囲を回答するときに重要な話になります。

例えば、ECサイトで商品の詳細を表示する画面が見られないという事象が起きた場合に、
ある1件の商品のみが見えないのか、すべての商品が見えないのかで、
事象の深刻さは変わります。

また、見れない商品の数が少なかったとしても、
売り上げが多い商品なのか少ない商品なのかでも損失が変わります。

他にも、特定のブラウザや端末の特定のバージョンでしか事象が発生しないなど、
ユーザー側の環境で影響範囲が絞られるのか否かという問題などもあります。

障害である以上、どれくらい深刻な状況なのかということに相手は最も関心があるはずです。
深刻さを決めるのは影響範囲と復旧にかかる日数だと思うので、
数値(日数・影響が出たデータの数)や具体名(商品・顧客など)を使って具体的に報告しましょう。

感情を排し、事実のみを書く

こういったドキュメントを書くのは、多くの場合がエンジニアになると思います。

シンプルにミスしたという場合もあると思いますが、
時には技術的負債が表面化したり、短納期で急かされたなどの事情が絡んでいたりして、
そこに対する不満や憤りを持ちながら過ごすということもあるかと思います。

経緯を説明するときに、不満や憤りに起因するマイナスな感情が表面化すると、
報告書の趣旨からずれますし、無駄に心象を悪くするのでやめましょう。
(まともな人であれば、障害を作り込んだ本人を責めるようなことはしないですし、
再発防止策をどうするかを話題にするはずです。)

言い換えの具体例をいくつか書いておきます。
(「感情が混じっている例」の表現の方が、背後に被害者感情が透けて見えるはずです。)

感情が混じっている例	事実にフォーカスした例
短納期で無理なスケジュールを強いられた結果です。	スケジュールの関係で十分なテスト時間を確保できませんでした。
技術的負債が放置されてきた結果です。	過去の実装上の課題が今回の障害の一因となりました。
要求が頻繁に変更されたため、こうなったのは当然です。	要求の変更頻度が高く、対応が複雑化しました。

何を書くのか

表にしてまとめてみました。
具体例に関しては、エンジニア以外の人にも内容が極力伝わるように工夫した例と、
普段のエンジニア同士での会話では通じる例の両方を併記しました。

項目	内容	具体例（エンジニア以外向け）	具体例（エンジニア向け）
障害発生日時	障害が発生した日時を記載	2024年12月7日 午前10時30分	2024-12-07 10:30
障害解消日時	障害が解消した日時を記載	2024年12月7日 午前11時45分	2024-12-07 11:45
影響範囲	障害が及ぼした範囲を記載	システムAでログインができず、すべての利用者が影響を受けました。	システムAのログインAPIが応答せず、全ユーザーに影響が発生した。
障害概要	発生した障害の簡単な説明	リリース作業後にシステムのログイン機能が動かなくなり、エラーが発生しました。	デプロイ後、環境変数の不備によりログイン処理でエラーが発生。
発生原因	障害の原因を記載	必要な設定が正しく行われていなかったため、システムがエラーを起こしました。	環境変数LOGIN_API_KEYの設定ミス（誤った値が設定されていた）に起因。
影響規模	障害が影響した範囲や規模を記載	すべての利用者（約10,000人）に影響が出ました。	全ユーザー（約10,000人）
対応内容	障害対応の内容を記載	設定を修正し、システムを立ち上げ直しました。その後、問題が解消されたことを確認しました。	環境変数を修正後、サーバー再起動を実施。動作確認を行い問題が解消されたことを確認済み。
再発防止策	再発防止のための施策を記載	リリース作業前に設定の内容を自動でチェックする仕組みを導入します。	CI/CDパイプラインに環境変数の事前検証を追加。
教訓・気付き	今後の改善に役立つ学びを記載	設定管理の手順をもっと簡単でわかりやすくする必要があると気づきました。	環境変数の管理ツールを導入し、手動ミスを防ぐ必要がある。
備考	補足情報や関連情報を記載	ログインが必要になる場合があるため、利用者へのお知らせを準備しました。	APIキー更新に伴い、一部ユーザーで再ログインが必要となる場合がある。