Interactive Runbooks: Code, Not Text

The Problem with Static Wikis

Most runbooks live in Confluence or Google Docs. This creates three friction points that compound under pressure:

1. Context switching: You read the doc, Alt-Tab to the terminal to run the command, Alt-Tab back to read the next step. Under stress, you lose your place.
2. Copy-paste errors: You copy a command from the wiki, paste it slightly wrong, and introduce a new problem into an already broken system.
3. Staleness drift: The wiki says "Run script /usr/bin/cleanup-v1.sh", but the server now has v2.sh and v1.sh no longer exists.

Each of these is a small friction point in isolation. At 3 AM during a SEV1, they compound into significant delays and mistakes.

Enter the Executable Runbook

The solution is to merge the documentation and the execution environment into a single interface. The most common tool for this is Jupyter Notebooks, though similar patterns exist with tools like Runme (a VS Code extension that makes Markdown executable) and internal platforms built at companies like Netflix and Slack.

In an executable runbook, code snippets are not text — they are live cells you can run directly in the document:

• Step 1: "Check Traffic." → Click ▶ → A graph renders inside the document, pulling live data from your metrics system.
• Step 2: "Restart the Cache Service." → Click ▶ → The restart command executes against the server via a pre-authenticated API call, and the output appears below the cell.
• Step 3: "Verify Recovery." → Click ▶ → The error rate graph refreshes and shows the drop.

The engineer never leaves the document. There is no Alt-Tab, no copy-paste, no terminal session to manage.

The Trade-offs

Executable runbooks are powerful but not free. They require:

• Pre-authenticated access: The notebook environment needs credentials to reach your infrastructure. This is a security surface that must be managed carefully (short-lived tokens, audit logging).
• Maintenance of the execution environment: If the Python library that queries your metrics API changes its interface, the notebook breaks.
• Organizational buy-in: Engineers need to trust the tool enough to actually use it during an incident rather than falling back to their terminal.

For teams that invest in the infrastructure, the payoff is significant. For smaller teams, a well-structured static runbook with copy-pasteable commands is still far better than no runbook at all. Do not let perfect be the enemy of good.