Jamf Blog
October 19, 2017 by Joshua Oakes

Never too late for great documentation

Learn the basics of process writing and discover how to improve the quality of your documentation almost immediately.

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. A good example of incorporating screenshots into a process document can be found here in our Knowledge Base. For more complicated processes, a process diagram is often valuable to help people visualize the pathway. We have a blog post with tips on creating great process diagrams.

Have questions or want to keep this riveting documentation conversation going? Well, if you’re attending the Jamf Nation User Conference, you’re in luck! We’re a proud sponsor, so swing by booth 1 throughout the event and let’s discuss how you can become the guru of documentation.

Joshua Oakes is a content writer at IT Glue.

Joshua Oakes
Subscribe to the Jamf Blog

Have market trends, Apple updates and Jamf news delivered directly to your inbox.

To learn more about how we collect, use, disclose, transfer, and store your information, please visit our Privacy Policy.