How to Review Technical Documentation

Let’s talk about reviewing technical documentation. This topic is discussed in the techcomm community a lot since it is the cornerstone of a good help writing workflow.

Before analyzing approaches to reviewing, we would like to draw your attention to the fact that having a convenient environment tailored to reviewers’ needs is the first step you should take to improve the review process. So, it all starts with the technical writing software you are using. Make sure it allows setting up an effective process.

Sending files for review via email is an obsolete workflow that often causes confusion and some technical documents can even be lost along the way. Luckily, modern help authoring tools are here to save the day. For example, ClickHelp has a special reviewer role available, this feature alone can bring quick improvements. But there’s more: in ClickHelp, you can instantly add and manage review notes and to-do lists. We recently enhanced this functionality as part of the ClickHelp Aurora Polaris update.

Key Documentation Review Stages

Tom Johnson from Idratherbewriting singles out five review stages in his blog:

• Review with the doc team
• Review with the product team
• Review with the field engineers and support group
• Review with legal
• Review with beta partners

If content goes through these five stages it should be stripped of all major bugs for sure. Each stage has a different team responsible for content review and they all are essentially looking for issues in different areas. This way, technical writers can get maximum coverage. The overlapping areas do not feel like a waste of time either, on the contrary, this just means more thorough checking.

We overall agree with Tom’s approach, however, we would like to shift focus a little towards post-publishing stages of a technical documentation lifecycle.

The idea that before user manuals are published, they should be as bug-free and precise as possible seems legit. Nevertheless, in agile software development things need to be happening fast, which can lead to quality loss. Let’s not forget about the fact that a documentation team’s workload heavily depends on devs and QA. So, short notice changes in documentation plans are something one needs to be prepared for.

When technical documentation is published, things get real as your clients become your reviewers. To succeed at this stage, make sure to follow up on every issue reported by the clients as soon as possible. Another critical aspect of this process would be effective collaboration with the support team. Support team members reference technical documents all the time, and they are the first to receive user complaints, as well. So, this cross-team communication channel needs to be open and allow quick back-and-forth data exchange.

Returning to Tom Johnson’s article, we would like to mention that Tom and his blog on techcomm made it into our list of the top technical writing bloggers. Thanks for great content, Tom!

Conclusion

A smooth and robust review process is critical for technical writing teams as the content quality depends on it directly. Every team has a unique review process that meets their requirements. Hopefully, with this article, we made this complicated topic a bit simpler and you will be able to use some tricks in your workflow.

Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices