Operational knowledge

Operational documentation is read under pressure, usually by somebody who did not write it. A diagram in the runbook saves more time than any amount of prose, provided it is accurate.

Accuracy is the constraint, which is why generated and text-based diagrams suit this best.

#When to draw one

• Runbooks and incident procedures.

• Network and infrastructure documentation.

• Escalation paths, which nobody remembers at 3am.

#What is on the diagram

#A worked example

An escalation path, in the form somebody needs at 3am:

The source, which you can paste into a new diagram and edit:

flowchart TD
  A([Alert fires]) --> B[On-call acknowledges within 5 min]
  B --> C{Acknowledged?}
  C -- No --> D[Escalate to secondary]
  C -- Yes --> E{Resolved in 30 min?}
  E -- Yes --> F([Close and write notes])
  E -- No --> G[Page engineering lead]
  G --> H{Customer impact?}
  H -- Yes --> I[Open incident channel and notify support]
  H -- No --> J[Continue investigation]
  D --> E

#A few things that catch people out

• Put real names and real numbers on it. A generic diagram is useless in an incident.

• Date it and name an owner. Operational diagrams age faster than any other kind.

• Link the diagram from the alert itself if your tooling allows it.

#Related

Diagrams next to the words they explain.