Runbook with a live diagram: the first two minutes of an incident

Incident response has a shape. Orient, hypothesise, act, verify. Runbooks are almost always written for the act phase, by someone who was already oriented when they wrote it, which is why they open on a command and not on a map. The responder who most needs the runbook is the one who has never touched this service, and they are stuck at step zero.

The orientation questions are structural, not procedural. Which datastore does this write to. Is that queue upstream or downstream. Who calls this, and will they retry or drop. Prose can express those relationships, but it takes a paragraph to say what an arrow says instantly, and paragraphs are the wrong medium for someone reading at 3am with an alert still firing.

Putting the picture above the procedure changes the runbook from a script into a map with a script attached. It also makes the runbook usable for the second most common case, which is not an outage but a person trying to understand a service quickly.

Runbook diagrams are almost always screenshots pasted at the moment of writing, and runbooks are written after an incident, which is the moment the system is least likely to stay still. The migration lands, the restart command changes, the queue moves to a managed service, and the image keeps showing the old shape with total confidence.

The classic example is a service migrated to Kubernetes half a year ago whose runbook still lists the old restart command next to a diagram of the old topology. Both are wrong in the same direction, and both are trusted under pressure, which is what makes a stale runbook diagram worse than no diagram. An absent picture makes a responder go look. A wrong picture makes them act.

The other slow leak is links. Runbooks accumulate pointers to dashboards, tracing views, and diagram files, and those pointers rot independently of the runbook text. Every review cycle that checks the steps but not the links leaves the leak running.

A live embed is one markdown image line at the top of the runbook page. It renders wherever the runbook already lives, a Confluence page, a Notion page, a markdown file in the repository, or a docs site, and it shows the current state of the canvas rather than a copy taken when the runbook was written.

Viewers need no account, which matters more for runbooks than for anything else in the documentation set. The person paged at 3am might be a contractor, a person from a neighbouring team, or someone whose SSO session expired. A picture behind a login is a picture that is not there when it counts.

Because the diagram is generated from the repository, the topology it shows follows the infrastructure code rather than the memory of whoever wrote the runbook. When a queue is added in a merged pull request, the next sync shows the queue.

The split is the same one that works everywhere else in documentation. Thresholds, escalation paths, the order to try things in, the caveats about what not to restart during business hours: all judgment, all written by people, all slow to age. The topology and the dependency map: derivable, fast to age, worth generating.

Practically, that means a runbook page with a live diagram at the top, a short orientation paragraph naming the components in the picture, and then the procedure. Review cycles then focus on the procedure, which is where human attention is actually needed.

The notes you add on the canvas survive the regeneration, which is what makes this workable rather than theoretical. A node someone added by hand carries no source id, so the next generation is told to keep it as the reader's own work instead of reconciling it away. A node dragged more than twelve pixels from where the previous sync left it counts as hand-placed and is put back exactly there. So the annotation reading do not restart this during business hours stays beside the box it is about, sync after sync, while the topology underneath it keeps following the infrastructure code.

When you do need a still, for a postmortem document or an incident report that must reflect a specific moment, export the canvas as PNG or JPEG and date it. A frozen picture in a postmortem is correct, because a postmortem describes a moment.

• Keep incident runbooks up to date
• Stale runbooks and incident risk
• Keep runbooks in sync with infrastructure
• Embed diagrams in Confluence
• Live embeds: one markdown line