Let’s say you’ve got your documentation system in place. You’re working on building a documentation culture in your team. You’re living the good life on the road to documentation zen.
All is going well until you notice a pothole. Then another. And you realize that you’re documenting processes, but some of them don’t make sense except to the person who wrote them. Don’t worry. This can be fixed. There’s a process to documenting processes.
If your team is having trouble creating quality process documentation, that’s normal. There's a reason technical writing is a profession unto itself. However, the basics of process writing are pretty easy to understand, and just implementing the fundamentals should improve the quality of your process documentation almost immediately.
Go start to finish
It may seem obvious, but sometimes people don’t do this. When documenting a process, describe it from the very beginning of the process to the very end. It might also help to draw a line chart to conceptualize the steps.
Brief introduction
Provide only the critical information about the process in the introduction. Avoid lengthy preambles. Just state what the process is for, what the end objective of the process is and how many steps there are. If you have to differentiate the process from a similar process, be as brief and direct with that messaging as possible.
Use sequencers
All processes are a series of steps. Break down the process into these steps. Write the process in terms of the sequence of steps. Use numbers, bullets or phrases such as “first of all”, “next” and “finally”. This tells the reader that you have moved on to the next step.
Each action should be associated with a single point in the sequence. Each action should follow the previous action, and precede the following action. Do not skip steps -- write even the obvious ones.
Less is more
Describe all of the elements of the process, but nothing more. A process document should not contain editorializing, or asides. Be sparse in your writing and keep it simple.
Be careful with contingencies
Contingencies should be given their own sentences, located after the previous step. They should be written as ‘if x, then y”. Avoid long-winded contingencies. Each "if-then" sequence is its own step.
Avoid passive voice
The process document is a “how to”, so write it like you were giving instructions to somebody. Be as direct as possible.
Use visuals
Visuals can and should be used to lend clarity to process documents. Screenshots are a great tool for ensuring clarity. For more complicated processes, a process diagram is often valuable to help people visualize the pathway. Use a tool like LucidChart. Photos of things like server rooms can help put some of the description text into context as well – if you’re writing a “how to” it’s better to be looking at the room instead of trying to remember it. Better for the reader to see it, too.
There’s a lot more to it than this, but if you’re not a trained technical writer, this should at least provide a good starting point. Happy documenting!
Joshua Oakes is a content writer at IT Glue, which develops documentation software for MSPs. Read all IT Glue blogs here.
