Nobody reads a runbook at noon for fun. They open it when the pager has already ruined the night. If the first screen is a philosophy of the service mesh, they will close it and start guessing.
What belongs on page one
- How you know this is the incident — the alert name, the symptom, the dashboard or monitor link.
- Immediate checks — three to seven commands or clicks, copy-pasteable.
- Mitigations that buy time — rollback, feature flag, scale up, failover.
- When to escalate — and to whom.
- Where logs and graphs actually are — deep links, not "see observability platform."
Everything else — architecture history, old outages, owner trivia — goes below a fold or in a different doc.
Tone
Write like a text to a teammate:
- "Check if the last deploy was in the last hour: ___"
- "If error rate > 5% on login, disable ___ flag"
- "Do not restart the primary DB without ___ in the loop"
Avoid:
- "It is important to consider…"
- Undated screenshots of a UI that shipped two redesigns ago
- Commands that only work on your laptop
Length
One screen for the common path. A second section for "still broken." If you need a novel, you need smaller alerts — each page should map to a play, not to the whole product.
Keep them alive
After an incident, spend ten minutes on the runbook before the postmortem polish. Add the command that actually worked. Delete the step that wasted twenty minutes. Stale runbooks are worse than none because they create false confidence.
The gate
No runbook, no page. Put the link in the alert body. On-call should not hunt Confluence while customers wait.
Pair this with when to page vs notify and a real escalation policy. Tools route the person; the runbook tells them what to do when they arrive.