Runbooks: The Documentation That Actually Gets Used

Most companies that try to “document their systems” end up with one of two outcomes: nothing, or a long, ambitious document that was out of date the week after it was written.

There’s a better starting point: runbooks. A runbook is a short, step-by-step guide for a specific operational task. It isn’t a description of how a system works. It’s instructions for doing something with it.

Why runbooks work when other documentation doesn’t

The runbooks every critical system should have

Start with these, in roughly this order:

  1. System overview (one page): what it does, who uses it, where it’s hosted, what it connects to, and who owns it
  2. Access: where credentials live and how to get access
  3. Deploying a change: how code gets from the repository to production
  4. Restarting or recovering: what to do when it’s down
  5. Restoring from backup: where backups are and step-by-step restore instructions
  6. Rotating credentials: how to replace a password or API key without breaking things
  7. Common issues: the three or four problems that come up repeatedly, and how to fix them

That’s enough to remove most key-person risk from a system.

How to write a good runbook

Where to keep them

Close to the work. A folder in the code repository, a shared wiki, or a documentation tool your team already uses. The best location is wherever someone will look during an incident, and somewhere that doesn’t depend on the system being up.

The test that matters

Could a competent engineer who has never seen this system complete the task using only the runbook?

If yes, that knowledge now belongs to your company. If not, revise it and try again.

Keeping runbooks current, not ceremonial, is part of every managed software services engagement. For the broader process of regaining control over unowned systems, see The Orphaned Software Playbook.


Tell us what you're running.

Two quick steps. I'll read it personally and reply with an honest read on your situation and whether our team can help, usually within one business day.

  • I lead every engagement personally
  • No sales sequences, and your details are only used to reply

Prefer email? [email protected]

Step 1 of 2

Which sounds most like you?
What's prompting this? Pick any that apply
How many business-critical custom systems?
Timeline
Where should I reply?