This summer, we’re taking it back to school. Documentation Summer School, that is.
This is where those who are still near the beginning of their documentation journey can explore some of the fundamentals of creating great documentation, and a documentation culture. Some of this will be older material that’s still awesome, but there will also be new pieces designed to fill in the gaps of our previous work on the subject of mastering IT documentation.
The best thing about summer school is that it’s casual. Drop in, drop out, just as long as you learn something along the way. So let’s get started!
Let’s say you’ve got your documentation system in place. Something really good, like IT Glue. You’ve synced your PSA. 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.
Republished with express permission from IT Glue. For additional information go to www.itglue.com
Read the full story here – MSP Summer School: Writing Great Process Documentation
