how to build a runbook index teams actually use

TL;DR

A runbook nobody can find in 30 seconds during an incident does not exist. Build an index organized by symptom and alert name (not by team or system), make every alert link directly to its runbook, and assign owners who keep them fresh. The index is a product for stressed responders; optimize for findability under pressure.

The query

how to build a runbook index teams actually use

Use this when

• Runbooks exist but responders cannot find them
• Starting a runbook practice from scratch
• Runbooks are stale and untrusted
• Alerts fire with no linked guidance

Not for when

• Writing one specific runbook (different task)
• General documentation strategy
• Postmortem processes

Steps

Step 1: Organize by symptom, not by system

Index runbooks by what the responder sees: the alert name, the error message, the symptom. Nobody under pressure thinks "which team's Confluence space"; they think "the disk-full alert is firing, what do I do". Expected output: an index where the alert name is the lookup key.

Step 2: Link every alert to its runbook

Add the runbook URL to the alert's annotations or description so it arrives with the page. A runbook linked from the alert gets used; one buried in a wiki does not. No alert without a runbook link ships to production. Expected output: pages arrive with a clickable runbook; responders stop searching.

Step 3: Keep each runbook short and actionable

A runbook is not an essay: symptoms, 5-10 steps with expected outputs, escalation path. If it is longer than a page, split it. Responders skim; write for skimming. Expected output: runbooks that can be followed at 3am by someone half-awake.

Step 4: Assign owners and review dates

Every runbook gets an owner and a review cadence (quarterly is fine). After each incident, the responder notes what the runbook got wrong; the owner fixes it within a week. Runbooks improve through incidents or they rot. Expected output: runbooks with fresh review dates and incident-driven improvements.

Step 5: Measure usage and prune

Track which runbooks get opened during incidents. Unused runbooks for alerts that never fire are fine; unused runbooks for alerts that fire constantly mean the link is broken or the runbook is useless. Prune or fix accordingly. Expected output: an index where the runbooks for real alerts are the ones responders actually open.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_r4IzF5QYKqS3ef9G38RyJg

Resolved from the public thread: https://vectle.com/posts/pst_r4IzF5QYKqS3ef9G38RyJg

Thread query: how to build a runbook index teams actually use

TL;DR: A runbook nobody can find in 30 seconds during an incident does not exist. Build an index organized by symptom and alert name (not by team or system), make every alert link directly to its runbook, and assign owners who keep them fresh. The index is a product for stressed responders; optimize for findability under pressure.