Review: With a Little Help From Your Team

Conceptually, the review phase has perhaps the widest variation span in the entire life cycle. It may be as simple as a dedicated review status on your page. It may also depend on factors that are shaped by your product, the subject matter, your knowledge, your industry. It may require multiple approval steps and electronic signatures.

And, perhaps astonishingly, the review phase may blend seamlessly with the writing process.

One way or another, a review phase is, or should be, an integral part of your documentation life cycle workflow. Even the best writers can get lost in texts, subject-matter experts (SMEs) can get things wrong, etc. The easier the access for and cooperation with reviewers and your team, the more streamlined and efficient the process is. Do not box yourself in.

Let’s untangle the web and help you ask the right questions to ensure that your review process does not become a bottleneck in your documentation life cycle.

What Is a Documentation Review?

A good review process helps ensure that your content is accurate, helpful, and easy to understand. It helps catch gaps, clarify confusion, and improve consistency.

Not all reviews are the same, and you can group them into the following broad types – each of which comes with its own dos and don’ts:

Subject matter expert review

Ensures that content accurately reflects the product or process. For example, a developer might check if an API explanation is technically correct.

Peer review

Also known as second-pair-of-eyes. Its main purpose is to rectify anything that is a result of the author’s fatigue or blindness, a commonplace and fairly normal phenomenon caused by the fact that you, as an author who worked on the text for days or weeks, have become immune to the text’s flaws.

Style and language review

Focuses on grammar, tone of voice, consistency, and compliance with a style guide. Can be handled by anyone who knows what they’re doing and is familiar with your editorial standards. There are dedicated software tools, not necessarily AI-based, that can help in this phase. But AI grammar and spell check can help speed up this review type massively.

Usability review

Looks at the documentation from the user’s perspective. The goal is to make sure someone unfamiliar with the topic can understand and follow the content easily. This is often formalized and merged with the QA process.

When a Review Doesn’t Feel Like a Review

The review process can be built into the writing process itself in the form of iterative steps among the writer, the subject matter expert, and, for example, a product manager. It is a perfectly normal practice with multiple contributors alternating between writing and reviewing in a series of iterations.

You don’t even have to change the status of the page from ‘Draft’ to ‘Review’ as long as everybody is on the same… well, page.

Of course, this iterative process can be followed by a formal review phase or application of a quality control tool, if your process requirements demand it.

Or you can go straight to publishing knowing that your content was checked.

Reviews without workflows

Sometimes, workflow in your authoring environment is not enough. Or not even possible – but you still need to leave a trace of who participated in iterations.

If that’s the case, you can use issue/project tracking tools such as Jira by assigning the ticket to individual reviewers who would leave comments with briefs of what they have done.

Formal Workflows and Reviews

A review process can be formalized, built into a content workflow as a formal stage, and hardwired into your life cycle.

Your pages have statuses, from mere indicative labels that simply inform others about the stage of development of an article (new, draft, work in progress, review…) to hard-coded statuses that change the actual behavior of the content (for example, the person who drafted the article can no longer edit it).

A typical approach is to tie a status change to an automatic assignment to a specific person or role, often with a notification via email or Slack.

How exactly you structure your review process, how granular you make it, really depends on your specific situation. You may start with a technical review, follow up with usability checks, and put language checks at the end. But you might consider another subject-matter expert (SME) or usability round to check if anything might have been lost during the language review. It’s really easy to misread text, alter the grammar, and accidentally change the meaning completely.

Designing Fail-Safe Mechanisms

To prevent your review process from becoming a bottleneck, you can assign reviews to either a dedicated user group or multiple individuals. This ensures that the task will remain accessible even if one reviewer goes on vacation or becomes sick.

We’ve seen review processes so tight that they required a manual override from a system administrator because the assigned reviewer went on vacation.

You should always have a ‘return-to-sender' option in your review process – to the original author, to another reviewer, etc. It might also be a good idea to give the override authority to a specific person or role – this is especially useful if you need to fast-track a change in emergencies.

Regulations and Compliance

Reviews and strict workflows are matters of utmost importance in regulated industries – medical and healthcare, aerospace, precision manufacturing, safety equipment, legal. In these circumstances, both the end-user documentation and the documentation about processes for creating end-user documentation might be subject to strict approval regulations .

In practice, it can mean that only people with a specific role or qualification can (and/or must) conduct reviews. Multistage review processes and even electronic signatures are common.

Your compliance team will be able to advise and guide you in this matter, so make sure you ask them about any existing or potential compliance requirements.

Time-enforced reviews

On a related note, your compliance policies may require that you conduct a review of a documentation page at regular intervals to meet regulatory requirements – irrespective of actual updates.

This type of review is something that you should consider during your strategy phase as it requires building processes (and setting up tools) that are likely to affect all steps in your documentation life cycle.

Reviews and AI

It may come as a surprise to many, but implementing AI into the review process isn’t new. In fact, it’s been around for decades.

Have you ever used the ‘Check spelling and grammar’ option? If you did, you already used AI. While the spelling part simply checks words against a dictionary, checking grammar and syntax requires a complex package of IFs and THENs because Joe’s working is indistinguishable from Joe’s working. What’s the difference? The words that come later: Joe’s working tonight vs Joe’s working conditions. Verb vs adjective.

Next in the order of historical appearance were the apps that you could customize to check style and tone of voice – no contractions (she’s vs she is), passive vs active voice, naming conventions, capitalization, sentence length, etc.

In its current iteration, AI can do much more and can become the proverbial second pair of eyes, your peer reviewing teammate.

Using AI can massively speed up the review process. But it does come with a checklist.

• An experienced human should always review the AI’s review. Even if it's the author.

• Privacy is important. Ensure that you use AI tools that will not utilize your data to train the generic model.

• Check with your legal/compliance team if using AI tools (outside spelling and grammar) in any part of the review process is ok.

Your Review Process Just Leveled Up

Review is where your documentation goes from done to great. With the right tools, structure, and communication, you can build a document review process that doesn’t slow your team down, it powers them up.

The review phase emphasizes the need for everyone who is involved to be on the same page and work within the same context.

You see, the concepts of ‘being on the same page’ and the ‘single source of truth’, which are often applied to consumption, are just as important, if not more so, for content authoring and reviews. Don’t sandbox documentation; context is important to do a proper review.

Next up in the documentation life cycle: publishing your content and engaging with the readers.