A runbook has an audience of one.

A runbook works while the person reading it is the person who wrote it, because that reader silently repairs every gap as they go. They know the step that says restart the workers means the two on the old host as well. They know the ordering constraint that never made it onto the page. They supply the missing context invisibly, and because it is invisible, the document appears to work for everybody.

Give the same runbook to the second person on the team at eleven at night. The gaps are now load bearing. Every ambiguity resolves into a decision that reader is not equipped to make and does not know they are making. The document has not changed at all. Its audience has.

This is not a documentation quality problem and it does not get better by writing more. Prose about a system drifts away from the system the moment either one changes, and nothing enforces the connection between them. A script has the opposite property. When a script drifts, the release fails, loudly, at a moment when somebody is watching.

The thing a runbook cannot be

It cannot be reviewed in any meaningful sense. You can proofread it. You cannot diff it against what actually ran last time, you cannot test it, and you cannot tell from reading it whether it still matches the system it describes. Approving a runbook is an act of faith dressed as an act of governance.

A shell script that has grown over two years is executable. It is not reviewable, and the gap between those two words is the entire subject of this company.

Reviewable means that a competent colleague can read the file once, form an accurate expectation of what is about to happen, and point at the step they disagree with. That is a stronger requirement than correctness. A correct file nobody can hold in their head buys you nothing on the night it matters, because the person watching it run has no model of what it should be doing and therefore cannot tell when it stops doing it.

Three things that quietly destroy it

• Indirection. Every hop into another file costs the reader their place. After five hops they stop following and start assuming, and an assumption is exactly what the review was supposed to catch.
• Configuration that changes behaviour. When the same file does different things depending on a value the reader cannot see from the file, reading the file no longer tells them what will happen. It tells them what might.
• Steps that are not in the file. One manual step in the middle is enough. The reader now has to know it exists, know when it happens, and know whether they are the one doing it.

The tooling exists to make those three expensive rather than convenient. That is a narrow ambition, and we would rather state it narrowly than dress it up as a platform.

We are only willing to publish the five properties because most of them are mechanical. A property that depends on somebody remembering it is a property that survives until the first bad week.

• An unreadable plan. A team of four reads the plan output and still cannot say what the release will do. That would mean the format is the problem rather than the runbook, and the format is ours.
• Release files that fork. If they become as long and as branched as the runbooks they replaced, we have moved the mess rather than removed it, and moving a mess into a repository makes it look governed without making it better.
• A gate that is a formality. Second readers who approve without reading are worse than no gate at all, because the approval manufactures a record of a review that did not happen.

Each of the three is observable from outside, and where we hit one it goes on this page in the same words used above. A falsification test kept privately is not a test. It is a way of feeling rigorous.

The fastest way to put the argument under strain is somebody else's deploy. Send us your worst one — the release that ran long, the step that turned out to be manual, the rollback that could not be rolled back — to hello@scriptshift.cc. What comes back is a straight read on where a single reviewed file would have caught it and where it would not, inside 5 working days.