Documentation is always essential for technical systems but it can be hard knowing where to start when staring at an empty page.
In this post I will attempt to explain what I consider a runbook to be, what its purpose is, and what I write in it.
Runbooks? Playbooks? Something else?
The Internet is awash with different definitions but I like Amazon’s description of a runbook and playbook, but lots of people consider both to be synonymous. Whether this is important to you is a matter for you to decide!
To summarise Amazon: A runbook documents steps to achieve an outcome and a playbook documents steps to resolve an issue.
Ultimately, whatever you call it it’s documentation!
Analysis of a runbook
Key information
It can be really difficult knowing what to write in a runbook. How much detail do you go into? Who is the target audience?
When I create a runbook I have a title, brief description of the runbook’s purpose and a table at the top of the document:
In most cases the Requirements will be a list of things like:
- Read access to the Foo GitHub repository
- A valid API key to Some External Service
- The following customer details:
- Email address
- User ID
I like to make the requirements as obvious and specific as possible.
The Escalation is used if the person following the runbook has any problems or has questions. This should ideally be a team rather than one person!
The steps
This is the meat of the runbook – the stuff that matters!
Probably the biggest mistake that can be made is either not having enough information, or having too much. Use the Requirements you listed to determine what type of person is likely to follow the runbook. Do they have server access? Chances are they know at least the basics.
Keep the steps clear and concise; using lists can help provided you can keep most of them to a single line.
Here’s an example for our dummy runbook:
Steps
Each of the steps above should be clear enough to follow.
Sometimes steps can’t be nicely summarised in a list. In that case, I like to simply use headings for each section. It’s important to try to keep free text concise though.
Troubleshooting
I like to include a troubleshooting section that can list any expected failures or problems with the runbook. Of course, you don’t want your runbook to be unreliable but there could be edge cases that can be noted.
Other tips
Make use of call to actions such as warning, note, and informational blocks. These make a welcome change from paragraphs of plain text and can help highlight important details.
Continuous improvement
Finally, allow others to edit your runbook! People should be able to fix typos and correct or update particular steps in the process without having to contact you. Encourage colleagues to create their own runbooks by establishing a common template that has a consistent layout.
This is my preferred approach to creating runbooks but I would love to hear what you do differently! Let me know in the comments.