Runbooks

A runbook is not documentation about the system — it is a script for a specific person in a specific bad moment: paged at 3am, half-asleep, unfamiliar with this particular service, under pressure to fix it fast. Write for that reader, not for someone doing a leisurely deep-dive at their desk. If the runbook requires understanding why the fix works, it has already failed its purpose.

The test of a good runbook is whether someone who has never touched the service could follow it and resolve the issue. If it only works for the person who wrote it, it is a note to self, not a runbook.

Write for a tired stranger, not for yourself.

1. Trigger the runbook from the alert, not the other way around

A runbook nobody can find during an incident does not exist. Every alert that pages a human should link directly to the runbook for that specific failure — not a wiki search, not "ask in Slack," a direct link in the alert payload itself.