Runbooks Nobody Reads and How to Fix Them

The Runbook Graveyard

Every team has one. A wiki section, a shared folder, maybe a pinned Slack bookmark titled "Incident Playbooks." Inside: dozens of documents written with good intentions during the adrenaline crash after a real outage. Most of them were accurate for about two weeks. Now they describe services that have been renamed, dashboards that no longer exist, and escalation paths to people who left the company.

Nobody reads these runbooks. Not because the team is lazy, but because everyone learned — through one or two painful experiences — that following an outdated runbook during an incident is worse than having no runbook at all.

The problem is not that people refuse to write documentation. The problem is that documentation rots faster than code, and nobody treats that rot as a bug.

Why Runbooks Decay Faster Than Code

Code gets exercised. Tests run against it. Users hit it. When it breaks, someone notices. A runbook sits inert until the exact situation it describes happens again — which might be weeks, months, or never.

Meanwhile, the system it describes keeps changing. A threshold gets tuned. An alert fires from a different source. A manual step gets automated. Each small change makes the runbook a little more wrong, and nobody updates it because nobody is looking at it.

There is also a cultural problem. Writing the runbook feels like the virtuous act — the postmortem action item with a green checkmark. Maintaining the runbook feels like overhead. So teams optimize for creation and ignore maintenance, which produces exactly the wiki full of fossils you would expect.

The 90-Day Rule

A blunt heuristic: if a runbook has not been opened in 90 days, delete it.

This sounds aggressive. It is meant to. The point is not to destroy knowledge. The point is to force a choice: either this document matters enough to keep current, or it does not matter enough to keep at all.

A runbook that nobody opens in 90 days is one of two things. It covers a scenario so rare that the document will certainly be stale when that scenario finally arrives. Or it covers a scenario that the team now handles through muscle memory, automation, or a different process. Either way, the runbook is not helping. It is adding noise to the search results when someone is looking for the runbook that would actually help.

Delete it. If the scenario comes back, you will write a better version with fresher context.

Tie Every Runbook to a Trigger

The runbooks that survive are the ones attached to a specific event. Not "how to debug high latency" — that is a topic, not a trigger. Instead: "this alert fired, here is what to do next."

When a runbook is bound to an alert or an incident category, two good things happen. First, the person who encounters the trigger can find the runbook without searching. A link in the alert payload, a reference in the incident channel template — the path from problem to document is short and obvious. Second, every time that trigger fires, someone opens the runbook. If it is wrong, someone notices while the context is hot, not six months later during a documentation audit nobody wanted to attend.

Runbooks without triggers are essays. Essays belong on blogs, not in your incident response tooling.

Review on a Cadence Shorter Than the Shelf Life

Even trigger-bound runbooks decay. The fix is a review cadence shorter than the expected shelf life of the content.

If your infrastructure changes meaningfully every month, reviewing runbooks quarterly is too slow. You will always be one cycle behind. A monthly review — brief, focused, attached to a real team meeting rather than a standalone ceremony — keeps documents within striking distance of reality.

The review does not need to be thorough. Three questions per runbook:

• Did anyone use this since the last review?
• Is the first step still correct?
• Is the escalation contact still right?

If the answer to the first question is "no" for three consecutive reviews, you are back to the 90-day rule. Delete it.

Less Documentation, Used More Often

The instinct after an outage is to write more. More runbooks, more diagrams, more wiki pages. This instinct is understandable and wrong. Volume is not coverage. A team with five accurate, regularly used runbooks will respond faster and more consistently than a team with fifty stale ones.

The goal is a small set of living documents that people actually trust. Trust comes from accuracy, and accuracy comes from use. Documents that get opened get corrected. Documents that get corrected stay useful. Documents that stay useful get opened.

That is the loop. Everything else — the wikis, the Confluence spaces, the "we should document this" action items that never get a second look — is theater.

Write less. Use it more. Delete the rest.