Runbooks for a smaller team. Write down the damned part you know.

It's three in the morning and your runbook[1]Ref. 1runbook en.wikipedia.org says "verify that processing is normal."

Wonderful. What the fuck is normal? Where do you look? You have written down a request for somebody else to know what you know, and then apparently gone to bed.

I wrote dozens of runbooks at Sprint[2]Ref. 2Sprint en.wikipedia.org, along with escalation matrices and root cause analysis[3]Ref. 3root cause analysis en.wikipedia.org reports. They helped the mediation operations team go from twelve people to four without losing coverage. The Director of Network Operations cited my documentation for helping other people understand the platform.

Please don't read this as my enthusiastic recommendation to cut a team to a third of its size. Documentation gets knowledge out of somebody's head, but it does not manufacture eight more people. I can write a damned good runbook, but it won't answer a second phone.

These are the standards I'd use to review a runbook now, by the way. They aren't excerpts from the Sprint documents. I'm describing how I'd want the next person to work from evidence, without having to borrow my memory.

Where does it run? What access do you need? Does it change anything? What does the result mean? The command is only part of the instruction. The rest is usually the part its author forgot they knew.

I want the recovery procedure to say what can safely restart and what evidence needs preserving first. And I need to know what observations mean we're outside this procedure now, before somebody tries to keep going.

When the state is uncertain, I'd want the operator to stop, preserve the relevant evidence and contact somebody who can resolve that uncertainty. Don't make an operator improvise data recovery because you ran out of paragraphs. That's a hell of a place to discover the documentation budget ended.

I'd hand the procedure to somebody who didn't write it and ask them to explain what they'd do next. If I have to lean over and say "what that means is," that's something I still need to put on the page before I go to bed.