Documentation
The Builder turns a plain-text runbook into an interactive runbook: one HTML file that anyone can open in a browser and follow step by step. These pages cover writing the plain-text runbook, building and handing over the interactive one, following it, and fixing what goes wrong.
Where to start
- Writing a runbook? Read Designing a good runbook before your first one; it is about what makes a runbook work for the person who follows it. Formatting for the Builder is the reference for laying out the text. Using the Builder covers building it and handing it over.
- Following one? Following a runbook explains what you will see and how your progress is kept.
- Something wrong? Troubleshooting lists every message the Builder gives, with the fix.
Drafting with an AI tool? The download includes runbook-design-guide.md, a file written for Claude, ChatGPT, Copilot and similar tools. Give it to the tool with your request and you get back a plain-text runbook that follows these rules and is ready to build.
First time? The download also includes sample-runbook.txt, a runbook that only reads from a Windows computer. Drop it on the Builder to see an interactive runbook before you write your own.
Terms
- A plain-text runbook is what you write: a
.txtfile laid out as Formatting for the Builder describes. - An interactive runbook is what the Builder makes from it: a single HTML file that anyone can open in a browser and follow step by step, with a Copy button on each block of code, a Done check box on each step, and fields for the settings. It works opened from disk, with no install and no network. Steps unlock in order: a step can be used once the step before it is checked Done.
- The operator is the person who follows the interactive runbook.
The pages
| Designing a good runbook | What to decide before you write, the parts of a runbook, how to write a step, testing and upkeep, and the checklist to run through before you hand one over. |
| Formatting for the Builder | The layout of a plain-text runbook: the header, sections, steps, comments, settings, and the rules the Builder checks. Ends with a complete example. |
| Using the Builder | Getting the Builder, building an interactive runbook, checking the preview, and publishing it with its hash. |
| Following a runbook | For the operator: the step list, Done and Copy, the Settings fields, keeping your place, printing. |
| Progress files | What a progress file holds, how it is loaded, and how to use it as a record of a run. |
| Troubleshooting | Every message from the Builder and from an interactive runbook, what causes it, and the fix. |
| Release notes | What changed in each version, newest first, with the name and hash of each release zip. |
| License | The terms for using the Builder and the runbooks it builds. |