Discover more from Runbooks Blog
Starting a Runbook from Scratch
A layered approach to writing runbooks with the least effort possible.
Starting with a blank page can be daunting. Fortunately, when writing a runbook, you have a head start: the actual process you want to document. Chances are, you already know how to do that process rather well, and doing the same thing you always do is a great way to begin writing the runbook.
This guide describes multiple levels of refinement when writing a runbook. You can stop at any level and still have a useful product. In fact, it will probably make sense to stop at a different level for each runbook. That way, you can get the most value for the least amount of work.
Level 1: Take brief notes as you perform the process
Start by doing the process as you usually would the next time it comes up naturally. As you go along, take quick notes for yourself about each individual step you take. These notes are merely to jog your memory later on, and to ensure you don't miss anything important. Don't feel compelled to write so much that you distract yourself from the job at hand.
The result of this level is a partial set of ad-hoc bullet points outlining what you did this time around. It's fine if these don't make much sense to another person yet.
Level 2: Add any optional steps you didn't need this time
Most processes have steps which you only do some of the time. Take a moment now to add in any missing steps you didn't happen to need this time, but might have needed if the situation were different.
The result of this level is a complete set of ad-hoc bullet points which fully describe the process, including the optional or conditional steps. It's still fine for it to be messy and hard to understand by someone else at this point.
Level 3: Expand your notes into step titles
As we've talked about before, each step in a quality runbook has a title (aimed at experts) and a description (aimed at novices). You now want to expand your quick bullet points into proper titles. Since titles are aimed at experts, these should:
be short (less than a dozen words)
be complete, imperative sentences (i.e., a command)
assume the reader has already done this many times before
The result of this step is a set of simple, clear imperative statements which would be good enough to remind a knowledgable person of which things to do, in what order. It may still be impossible for a novice to follow at this point.
Level 4: Add a description for each step
Now it's time to add the information a novice would need to correctly complete each step. It's easiest to do this by thinking of the last person you taught the process to (or the newest addition to your team), and imagine you are writing specifically for them. Here are some questions to help you figure out how much detail to include:
What did they already know before they got here?
What things were new to them?
What's different about how this process is done here versus other places?
Are there any screenshots, pictures, etc. which may be helpful?
Is there some example you can provide for the reader to copy from (e.g., an email template)?
Are there further resources outside the runbook you can link to?
The result of this step is the first complete draft of your new runbook. It will have everything needed by novices and experts alike to at least make a decent attempt at completing the process. It may still have typos, unclear sections, missing optional steps, or other minor problems.
Level 5: Refine the titles & descriptions
As you would do with any writing, now it's time to edit your work. Read through your runbook looking for all the same kinds of things you would look for with any other writing. In addition, you'll want to look out for these problems which specifically apply to runbooks:
Do your titles address "how" to do it, rather than "what" to do? Issues of "how" belong in the description rather than the title.
Do you include details which might change? People, phone numbers, email addresses, etc. are all things which often change. Instead, refer to roles (e.g., the IT admin), or a more generic way to contact the right person (e.g., a Slack channel).
Do you use abbreviations or terms which are specific only to your company? Since these documents will often be read by newcomers, it's best to only use abbreviations or terms which are widely known in your industry. At a minimum, all such terms should be clearly explained when they are first used in each runbook.
Do you make full use of images, bulleted/numbered lists, tables, and other formatting?
Do your descriptions include more detail than is needed? You should aim to explain only those things a typical newcomer wouldn't already know about how you happen to do this process in your company. You don't want to duplicate reference material you could link to, or explain things most people in your field already know.
The result of this step is a refined draft of your runbook. It should be free of common errors (typos, grammatical errors, etc.), and should be well-targeted to the needs of both novices and experts on your team. It may still be missing steps you didn't discover in Levels 1 & 2.
Level 6: Perform the process again using the runbook
No matter how careful I am, I have never yet managed to write the perfect runbook on the first try. There's always something I forgot which I don't notice until I try to execute the runbook myself. So, now it's time for you to pretend to be the new person, freshly arrived, and attempting to perform this process for the very first time with only your runbook for guidance. Ideally, you'll do this the next time you really do have to perform the same work again. Here are some things to keep an eye out for as you go along:
Is everything you're doing actually written down, or are you filling in pieces from memory?
Do you actually do the steps in the order listed?
Will a new person have all the tools and software you're using? Might they be using a newer version which works differently?
Will a new person have the necessary access permissions and/or security clearance to perform each step?
If a step goes wrong occasionally, have you included the usual workarounds in your runbook?
The result of this step is a runbook which has been validated against reality and is much more certain to be something others can use without your help. It may still be possible that other people won't understand the particular way you phrased things, or that you haven't accounted for variations in how different people do various steps.
Level 7: Ask another person to follow the runbook
The last step is to ask for someone else's help to repeat Level 6. They will almost certainly find some points of your writing unclear, and may have a better way to accomplish certain steps. Naturally, you'll want to ask them to keep an eye out for all the same things you were looking for, but to also mention:
How does this runbook differ from how they perform the same process?
Does the runbook accurately represent what needs to be done (i.e., no missing or extra steps)?
Do they find anything confusing or unclear in the writing?
Do the details in the descriptions (e.g., version numbers, phone numbers, email addresses, URLs, etc.) match with the ones they use?
The result of this step is your "final" draft of the runbook. But... not really "final". Any process should be constantly re-evaluated to make sure it remains complete, correct, and is still most efficient way to accomplish the goal. So, you'll want to revisit your runbooks periodically to check that nothing has changed.
We built our product, Runbooks, to make using this process as easy as possible. Keep a browser window open off to the side to take quick notes, fill in descriptions when you get to it, and ask your teammates for a quick opinion. Runbooks gives you all the tools you need to rapidly refine your runbooks to just the right level.