How to Write a Runbook People Actually Read

Every team has a folder of runbooks nobody reads. They were written with good intentions, usually the week before an audit, and they are technically complete — which is exactly why they are useless. A runbook that lists every fact about a system is a reference document. A runbook someone reaches for during a tense on-call shift is something else entirely: short, ordered, and written for action.

The difference is not effort. It is who you picture reading it. Write for the version of your teammate who is half-asleep, slightly stressed, and just wants the system to be okay again — and you will write a runbook that gets used. Here is how.

The one-page rule

If a runbook does not fit on roughly one page, it is trying to be two things at once. A runbook answers "what do I do?" A design doc or a wiki explains "how does this work and why?" Both are valuable, but mixing them buries the three commands someone needs under twelve paragraphs of context.

So hold a soft limit: one page per system, per situation. If the deploy story is long, give deploy its own runbook. If there are ten failure modes, the runbook lists the top few by frequency and links out to the rest. Length is not thoroughness — findability is. A page someone can scan in ten seconds beats a chapter they will not open.

Write for the tired newcomer

Picture the reader precisely: someone competent but new to this system, on-call at an hour they would rather be asleep. Every choice follows from that image.

No unexplained jargon. If a term is local to your team, define it once or link it.
No "just." "Just restart the worker" hides the exact step. Say which worker, and how.
Verbs first. "Restart the payments worker" reads faster than "The payments worker can be restarted."
One action per line. A tired reader follows a numbered list, not a paragraph.

This is the whole reason the 2am test exists as a quality bar: if your runbook would help someone groggy and unfamiliar, it will certainly help the rested expert. Writing for the hardest reader makes it work for everyone.

The anatomy of a runbook

A runbook is the same shape every time, so people always know where to look. The handover checklist lays out the full six sections; here is how to write each so it earns its place:

Overview — two sentences. What it does and who owns it. Resist the history.
Access & on-call — the links a responder needs and how alerts are wired. Point to where access is granted.
Deploy — the safe path to ship, as numbered steps.
Rollback — how to undo, and how to confirm it worked. Make this the clearest section on the page.
What breaks and why — the honest, human section: the sharp edges and their fixes, ranked by how often they actually happen.
Links & where the secrets live — pointers out, including the name of the secret in your store.

Show the commands, exactly

The fastest way to lose a reader's trust is an approximate command. "Run the migration script" sends them hunting; `./bin/migrate --service payments --confirm` lets them act. Paste the real commands, with the real flags, formatted as code so they stand out.

Where a value changes per environment, show the shape and name the source: `deploy --token "$DEPLOY_TOKEN" # from the secrets manager, service/deploy`. The reader sees exactly what to type and exactly where the sensitive part comes from — without the sensitive part ever appearing on the page.

When you write a step, ask: "Could someone copy this and run it, or do they have to interpret it?" Interpretation is where tired people make mistakes. Remove it wherever you can — exact commands, exact file paths, exact button names.

What to leave out

Good runbooks are defined as much by what they omit. Leave out:

Backstory. Why the service exists belongs in a design doc, linked, not inline.
Everything that never happens. The failure that occurred once in three years does not earn a spot above the weekly one.
Anything that will rot fast. Exact instance IDs and today's dashboard URL age badly; link to a stable dashboard or a query instead.
Secrets. Always, without exception.

That last one is the hard rule, and it deserves its own reminder:

A runbook holds knowledge, never credentials. If a step needs a token or key, name where it lives — "in the secrets manager under `service/deploy`" — and link to it. Never paste the value. That is what a runbook, not a secrets vault means, and it is what keeps your runbook safe to share, search, and read at 2am.

Test it before you trust it

A runbook is a claim: "follow these steps and the system will be okay." The only way to know the claim holds is to have someone else test it. Ask a teammate to run a routine task — a deploy, a practice rollback — from your runbook alone, while you stay quiet and watch. Every hesitation marks a missing line.

Do this once when you write the runbook, and again after any big change. It takes twenty minutes and it is the single highest-return habit in operational documentation. A tested runbook is a promise you can keep.

Keep it alive

The best moment to update a runbook is the moment reality proves it wrong. Finished an incident with a step the runbook missed? Add the line before you close the ticket. Renamed a pipeline? Fix the command that afternoon. This "write it down while it is fresh" habit costs seconds and saves the next person an hour.

Then, once a month, skim the runbooks for the systems you own and prune what has drifted. That is the entire upkeep. If you want the structure to start from, the free Quick-Start hands you the skeleton, and the Starter turns it into a full, worked template for your first real service.

Get the free Handover Quick-Start

The checklist and the six-section skeleton — ready to paste into your wiki or repo today.

Writing runbooks: FAQ

How long should a runbook be?

About one page. If it runs longer, split by situation — a deploy runbook, a rollback runbook — rather than making one page do everything. Findability beats completeness; a short page people can scan under stress is worth more than a thorough one they skip.

What is the difference between a runbook and a wiki page?

A runbook is a fixed shape written for action; a wiki is an open place for anything. Runbooks answer "what do I do right now," wikis explain "how this works and why." Keep them separate and link between them. There is a full breakdown in runbook vs. wiki.

Should I include exact commands or general steps?

Exact, always. Approximate instructions send a tired reader hunting and second-guessing. Paste the real command with real flags, and where a value is sensitive, name its source in the secrets store instead of writing the value itself.

How do I get my team to actually keep runbooks updated?

Make the update tiny and immediate: add the missing line the moment an incident reveals it, before closing the ticket. Pair that with a five-minute monthly skim. Small-and-now beats big-and-later every time, and it keeps runbooks trustworthy enough that people keep reading them.

Where should runbooks live?

Wherever your team already looks — plain Markdown in the repo, a wiki, or Notion. The shape matters more than the tool. Just keep credentials out and in a real secrets store, and point to them by name from the runbook.

Keep reading

Disclaimer: The Handover Folder is a documentation tool, not a secrets manager. Never paste credentials, tokens, or private keys into a runbook — reference them from your real secrets store.