📋

アラート対応は「判断」を書くな──再現性を生むドキュメント設計の原則

に公開
Datadog
monitoring
incidentresponse
ドキュメント設計
alerting
idea

こんにちは、株式会社 tacoms の tadokoro です。
この記事は tacoms Advent Calendar 2025 13日目の記事です🎄
https://qiita.com/advent-calendar/2025/tacoms-ai

アラート対応の品質は、問題に対する
知識の有無よりも判断箇所の多さが左右します。

しかし現場では、次のような属人化が慢性的に起きています。

  • ログでどこを見るべきかが、人によって違う
  • UI の自動装飾によって、重要な差分が隠れてしまう
  • 手順書の分岐が多く、読者に判断を丸投げしている
  • 外部サービスの UI 更新でドキュメントがすぐに陳腐化する

私は最近、社内のアラート手順書をリニューアルする機会があり、
チームからのフィードバックと実務の改善を通じて、
ドキュメントの仕上がりを決める“共通のルール”があると気づきました。

この記事では、その“共通のルール”を噛み砕きながら整理し、
実務的な「ドキュメント設計の考え方」をまとめます。

1. 観察可能性（Observability UX）を破壊しない

― UI は便利だが、アラート調査では“情報の破壊者”にもなる

アラート調査の失敗で多いのは、
「見えていると思っていた情報が、実は UI によって隠れていた」 という構造的問題です。

なぜこれが危険なのか？

  • UI は“読み手の負荷を減らすために”情報を省略する
  • しかしアラート調査は“微小な差異”こそが事実を左右する
  • よって UI による省略は「判断材料の喪失」につながる

つまり、UI の自動装飾は観測精度を下げてしまうのです。

具体例としては：

  • Notion の URL プレビューでクエリが省略される
  • Datadog がフィールド名を途中で切る
  • Retool がクエリパラメータを折り畳む
  • timestamp や env の違いが UI に吸収される

これらはすべて、「見えているようで見えていない状態」を作ります。

判断材料は「UI に依存しない形式」で残す
そのため、URLは必ず生テキストで残します。

観察可能性（Observability）とはログやメトリクスの話だけではありません。
“人間が気づけるように情報が提示されているか” というUXの問題でもあるのです。

2. コードを読まなくても伝わるように言語化する

― 読者に判断させないために、“必要な情報と役割”だけを書く

手順書でコードの説明を避けるべきなのは、
読者に理解を求めるためではなく、判断をゼロにするためです。

アラート対応はエンジニア以外も扱うため、
関数名や実装の話に依存すると次の問題が起きます。

  • 何が重要なのか伝わらない
  • 実装変更で手順書がすぐ古くなる
  • 読者の理解度により判断がブレる

悪い例（読者に判断を投げてしまう）

getShopId() が null なので、実装を確認してください。

何を見るべきか分からず、判断が必要になります。

良い例（必要な情報と役割だけを示す）

決済処理は以下の順です。

1. ドメイン（店舗を特定する）
2. shopId（対応する決済アカウント）
3. APIキー（決済リクエストの認証）

今回の異常は、このうち「shopId」が欠けている状態。
shopId が無いと APIキーが確定せず、決済リクエストを送れない。

そのため “shopId が存在するか” を見れば正常／異常が判断できる。

実装を知らなくても、何を見ればよいかが一本道で伝わることが重要です。

3. “見るべき場所”をあらかじめ整えておく

― 指定 URL を開いた瞬間に「必要な情報だけ」が揃っている状態を作る

2章で「文章で判断を明確にする」話をしましたが、それだけではまだ不十分です。
読者が迷うのは文章中だけではなく、画面上でも判断が生まれるためです。

例えば、Datadog は自由度が高いため 「どのログを開く？」
「どのフィールドを見る？」という判断が必ず発生し、属人化します。

理想はその逆で、

アラートのリンクを開いた瞬間に、必要な情報だけで整理された画面が表示されること

です。

そのために、URL 側で以下のように必要な情報を“固定”します。

  • Group by：url, errorCode
  • Columns：必要なフィールドだけ
  • viz：toplist / stream
  • flat_group_bys=true
  • 期間（alert_start / alert_end）

こうすることで、

  • ログ詳細を開く必要がない
  • 観るべき視点が完全に揃う
  • 正常／異常の差が一覧で判断できる
  • “どのログを見るか？”という判断が消える

つまり手順書は「操作方法を解説する場」ではありません。

大事なのは、判断すべきポイントをすべて書き手（筆者）が先に潰しておき、
対応者は淡々と進めれば同じ結論に着く状態を作ることです。

こうして UI 側で「見る場所」を固定しておくことで
Datadog は“判断する場所”ではなく、開くだけで必要情報が揃うビューになります。

4. 手順書は“一本道”で書く

― 手順書そのものの構造から判断を取り除く

3章では、UI や URL を固定して「画面上の判断」をなくす方法を紹介しました。
次に必要なのは、手順書そのものの書き方から判断を取り除くことです。

具体的には、手順の途中に「場合分け」や「判断を促す文」を置かず、
読者は書かれた順に進むだけで結論に着地できる形にします。

例えば：

  • 手順の途中に条件分岐を書かない
  • 判断が必要な項目は章の冒頭または巻末にまとめる
  • やることはすべてリストで一本道化する

こうして手順の中から判断を一つずつ排除していくと、
手順書は自然と「一本道」へ収束していきます。

この一本道こそが、誰が対応しても
同じ結果にたどり着ける再現性の土台になります。

まとめ：判断を排除することで初めて“再現性”が生まれる

結局のところ、アラート手順書が目指すのは
「誰が読んでも同じ結果にたどり着ける」こと。

そのためには、判断を筆者がすべて先回りして潰し、
対応者は画面と文章に沿って淡々と進めるだけにする。

これが、再現性のあるドキュメント設計の核心です。

手順書の役割は、判断をさせないこと。
これさえ守れば、再現性は自然とついてきます。

Discussion