The standard advice about runbooks is to write them. This is correct but incomplete. The harder question is when to write them and how to keep them accurate over time, because a runbook written at the wrong time or allowed to go stale is worse than a useful guide — it’s an actively misleading one that sends a responder down wrong paths during an incident, when wrong paths are the most expensive kind.

The best time to write a runbook is immediately after the first time you successfully resolve a specific kind of problem. Not the next day, when the details are still fresh but you’ve started forgetting. Not six months later, when you remember the category but not the specific flags you had to pass or the specific output you were looking for. Immediately after: while the terminal is still open, while the commands are still in your history, while you still remember the two paths you tried that didn’t work before you found the one that did.

The second-best time is during the incident itself — a running log of what you tried, what the output was, and what you did next. This produces a raw record that you can clean up afterward into a proper procedure. It’s more work in the moment, but it captures the diagnostic reasoning that’s easy to lose in retrospect. The failure modes that turn out to be dead ends are often the most valuable parts of a runbook, because they prevent future responders from spending time on the same dead ends.

The worst time is a scheduled “runbook documentation sprint” weeks or months after the fact. These tend to produce high-level summaries that omit the specific details that make runbooks useful: the exact query to run, the specific field to look at in the output, the threshold that distinguishes a problem from normal variation. The person writing the summary knows these things implicitly and often doesn’t realize they’re leaving them out. The person responding to an incident at 3 AM does not know them implicitly, and their absence is the difference between a fifteen-minute recovery and a two-hour one.

Keeping runbooks accurate is the other half of the problem. A runbook that accurately describes how to resolve an incident in the system as it existed eighteen months ago can be actively harmful in the current system, where the procedure has changed, the endpoint has moved, or the command has different flags. The simplest maintenance mechanism is a “last verified” date on every runbook, with a process that flags runbooks that haven’t been verified in the last N months for review. The review can be lightweight — just running through the steps in a staging environment to confirm they still work — but doing it before an incident is dramatically cheaper than discovering the mismatch during one.