Publication
Writing Runbooks That Actually Get Used
Most runbooks are written once and never read again. The problem isn't that engineers don't want documentation — it's that most runbooks aren't useful at the moment they're needed most.
Author
Dipto Thakur
Published
Reading Time
The 3am incident is not the time to read dense prose. Runbooks need to be designed for the degraded cognitive state of someone under pressure.
The Test
Would a competent engineer who has never touched this system be able to execute this runbook and resolve the incident within 20 minutes? If not, the runbook needs work.
Structure That Works
Every runbook should answer these questions in order:
Making Steps Executable
Commands should be copy-pasteable. Variables should be clearly marked. Side effects should be called out explicitly.
The Maintenance Problem
Runbooks rot. The only reliable solution I've found: link runbooks to the monitoring alerts that trigger them, and require runbook review as part of the post-incident process.