How to review your documentation with fresh eyes

Reviewing your documentation – it may not be fun, but it’s definitely necessary! Reviewing what you have written is a crucial part of the authoring process, and doing it poorly (or worse still, not at all) can reflect negatively not only on your product, but on your company as a whole. The consequences of poorly reviewed content could potentially mean losing customers as their trust in your product and company wavers. It may also result in increased expenditure if you have to increase the level of customer support you provide. Also, if you translate your documentation into other languages, you may face significant localization costs if it requires editing. This can mean time delays in getting your product to market, or release dates being pushed back.

At 3di, the quality of our documentation is a top priority. Read on to learn about some of the methods we use to review our documentation so your review process can be both more robust and more effective.

Reviewing while writing

While you may think of reviewing as the final part of the authoring process – something to worry about only after the first iteration of the content has been written – reviewing as you write can be more beneficial than treating them as two separate processes. As well as being useful for spotting spelling mistakes and other minor errors, reviewing as you write is a great way to sanity-check if the style and content of the section you are working on adhere to the overall document purpose, and are right for your target audience. At 3di, we have our Style Guide embedded in our template projects and keep our Content Plans a quick link away to make staying on track as easy as possible.

Considering your audience

Understanding your target audience is a must when creating technical documentation. That’s because your target audience directly determines the style of your documentation. Are you writing a technical manual for engineers working on a radar system, or for the end users of a home appliance? In either case, by the time you start writing your documentation, you should know who your readers are going to be. Despite this, it can be easy to lose sight of your audience during the authoring process. There are various aspects to take into account, and you may find that your documentation requires some tweaking to follow more closely the style and tone required for your target audience. Thinking about your audience while reviewing your documentation is a great way to make sure you are getting this right.

Breaking it down

Another effective way to review your documentation is to not only think of it as a whole, but to break it down into its constituent parts. This two-pronged approach allows for a more in-depth look at both the granular and the overall picture, helping you to effectively review both the structure and cohesiveness of your content. By first reviewing your documentation at the sentence and paragraph level, and subsequently at the chapter and document level, you may find that you spot inconsistencies and mistakes you would not otherwise have found using a standard reviewing approach. For example, at the sentence or paragraph level you may spot spelling and grammar mistakes, or incorrect conditioning or formatting irregularities, whereas at the chapter or document level you may get a better feel for the transition between topics, and the overall consistency of your documentation.

Peer reviewing

Everyone has heard that old adage of two heads being better than one. So what better way of reviewing your documentation than using the fresh eyes of someone else! Getting your content reviewed by a fellow team member with an intimate knowledge of the product will, more often than not, highlight any inconsistencies or errors that an author might easily miss during the writing process. One of the keys to a robust peer review process is having an agreed checklist of issues to look out for, and making sure everyone knows how to use it. Partly this is to make sure nothing gets missed, but it also helps ensure the peer reviewer is focusing on what really matters in each customer project context.

So, I’ve made the case that reviewing your documentation should be taken as seriously as the initial authoring. Not doing so will likely have negative consequences, and reflect poorly on both your product and your company. Fortunately, by using the methods we have discussed here, you can be confident of producing documents that will help build trust in your product and in your company. If you would like to read some more tips and techniques to enhance your documentation, read our blog post on proofreading your content. If you are interested in reading about the iterative nature of the writing process, you may like to take a look at this paper for an in-depth exploration and analysis of linear and non-linear writing models, and conceptions of the writing process.