The Art of the Review – by Swapnil Ogale

Introduction

A few years back, I was working on a project that involved multiple documentation deliverables. I was running to a tight timeline and was hoping to get at the very least, a usable draft out to our end users by a promised date. At a very crucial part of the project, a new Change Manager joined in and circulated the documentation to staff in the organisation who were not a part of the project, and sought feedback on the documentation. They came back with some feedback that was not only a waste of their time, but also added unnecessary friction amongst our project team.

What went wrong? 

While the other team members had the organisation’s best interest at heart, they were completely the wrong audience, or even the wrong people to review the documentation, as they had no context of the project, requirements or deliverables and were instead put in a tricky situation. Looking back, it made me realise how crucial it was to factor in reviews, subject matter experts, expectations, and goals of the feedback as part of the documentation lifecycle. 

As a matter of fact, doc reviews are undoubtedly the best endorsements in the tech writing process, yet they are often overlooked, underestimated or half done.

There is an art to reviews, especially when it comes to tech writing. 

Planning

There could be worse things than getting documentation reviewed, but there often aren’t. 

I was in the unfortunate position where, on a project the documentation was published without a proper review, due to various contributing factors. Our end users picked up these errors and provided some very strong feedback on the quality of the documentation. In a way, it was a bitter lesson to learn, but one that made the team review our process around documentation.

As a tech writer, you should plan for reviews in your documentation plan. Planning not only involves getting documentation ready for review, but also:

1. Identifying the number & type of people to get the documentation reviewed by, 

2. Building a relationship with them, 

3. Providing them with all the tools and reference information they need to provide actionable feedback, and

4. Allowing for multiple reviews and iterations of the documentation.

Peer review

Once you have a decent draft of the documentation ready for review, your first port of call should be a peer review if you have the luxury of working in a team. If you are working as a solo writer, and don’t have access to other writers, you could try and get a project team member with a strong interest in documentation to review the draft. 

In both cases, having a checklist of things to verify and validate will greatly help reduce the difference of opinions about the draft content. This is where a style guide comes in extremely handy, to resolve any style, language and grammar issues.

Here is an example of what things could be covered as part of this checklist:

✅ Grammar and punctuation

✅ Voice and tone

✅ Formatting and styles

✅ Adherence to standards (internal, style guides etc.)

✅ Organisation of content

I’ve often found that a peer review will often result in resolving a sizeable chunk of any inconsistencies or errors in the documentation. 

Product/business review

Once you have completed a peer review, you can take your drafts to the product team or the business to get a non-technical review of the documentation. 

The important thing is to set expectations on the type of review required. Product or business stakeholders can often get bogged down into the technical aspects or documentation style issues that should typically not be within their level of control. 

This review should ideally cover: 

• business context, 

• product expectations, 

• usability of documentation in relation to the requirements, and 

• suitability of the content for various audiences.

It is also a good idea to list out any prerequisites such as audience analysis, documentation planning and information research links that will help them review the content accordingly. 

Technical review

This review undoubtedly forms the core of the review process. Unfortunately, it is also the weakest link in the documentation process as it is often overlooked or taken lightly due to poor time management and prioritisation issues.

During the project planning phase, Project Managers often don’t plan any time for technical review of documentation and it is then an uphill battle to get any time from the technical team (developers, testers etc) to effectively review any content. It is important to advocate for technical reviews in the documentation process to ensure there are no issues with the content. 

Developers/engineers benefit from clear, accurate documentation as it not only complements the product they are building, but it also builds confidence that they can use this documentation in their interaction with the business and customers. 

In order to help developers/engineers effectively review the documentation, technical writers can provide them with a task list or a list of specific questions around the technical aspects of the content. This helps reviewers invest and focus on these specific areas and not worry about their business, grammatical or other issues. 

In addition to developers/engineers, you can also get the content reviewed by the support team as they are often the team with their ears closer to the ground than anyone else in the organisation. They are essentially a funnel for feedback directly from the end users, and can provide excellent perspective on what the users are looking for.

Right questions get you the right answers

This is a great productivity hack if you are trying to get your content reviewed to a degree where you, as a technical writer, are comfortable with publishing the content for end users. Asking the correct questions of the reviewers. A tip for doc reviews – bring a list of questions.

A lot of confusion and angst in the review process stems from the fact that reviewers are not given the correct instructions on what and how to review the content. Resultantly, they drift into aspects of the content that goes beyond their area of expertise. For example, business reviewers looking at grammar and language, or design aspects of the product itself. 

As a technical writer, you can help by creating clear guidelines on what to review, and the type of feedback sought. For example, if you are after technical review, you can send reviewers a list of questions around why the product works in one way and not the other, or clarify workflows within the product. These questions provide them with a perspective on the type of feedback required. 

Following up 

Once you have completed your initial reviews, the next (and hopefully final) step is to update your content with this feedback appropriately, and then following up on any clarifications or disagreements. 

To tie up any loose ends, you could have a quick catch up with the entire project team, including your reviewers to ensure you have covered everything from a technical and business/product viewpoint, before you finalise and publish your documentation. I prefer having a meeting in person as opposed to emails to close out any confusion or disagreements collaboratively and quickly. 

Providing feedback

Reviewing content is not the easiest task. Besides, you also need to be in the right frame of mind to review someone’s work. 

As a technical writer, you may be asked to review content that is created by someone else and possibly include within your documentation. How would you go about this?

How to provide feedback on content

At a previous workplace, I was a part of the local Toastmasters group and something I picked up there as part of public speaking, can also be equally applicable to reviewing content. It is called the PIPS (Positive, Improvement, Positive, Supply) method. The PIPS Method for Providing Feedback

Applying the PIPS method to review content:

P: Praise something specific

Focus on something specific that has been written very clearly and concisely and captures the message.

I: Suggest ways to improve

Provide practical ways to improve. Maybe point them to a style guide, or list out some examples to make something clear.

P: Provide overall praise

Praise the entire piece of content in its entirety. 

S: Supply uplifting comment

Provide positive reinforcement of the efforts and understanding.

If you had to apply this method to a piece of online help you have been asked to review, it would go something like this:

• I’d like to start by pointing out the well structured navigation for the online help. It helps me immediately identify what I am looking for.

• A couple of suggestions for improvement:

  • On page x, you have a couple of paragraphs explaining a rather complex procedure. You could look at maybe converting this to a table or a diagram for better readability. 

  • There are a couple of instances on pages a,b,c where you have used slightly different terms. I would advise using the same word for consistency and ease of understanding.

• Overall, I really like how you have managed to bring together a lot of complex information in a well presented and accessible format. 

• While there may be short term pain in convincing teams about the value of this online help, it will only help in the longer run if we can show how our end users have benefitted from this.

Doc reviews in agile environments

In an ideal world, you would do all of these activities in the previous sections, but things don’t often pan out this way, especially in busier (and fast moving) agile environments. Agile teams work in faster cycles and on short, disparate pieces of work, so getting a full review workflow is counter productive, as it can tie up team members into something that may be changed in later cycles of work. 

Working in agile teams, the docs as code method provides immense value, as you can build, discard, pivot and reuse content the same way as code for the product. This allows technical writers to write smaller blocks of content that can be easily reviewed and reused across multiple scenarios. 

A few years back, when I was working with the developers and QA to document product features, I added documentation and review cycles to our issue tracking tool (JIRA), so that any code change issue that affected documentation could not be closed until the corresponding documentation was reviewed and approved. While this added some bottlenecks at the start, the process smoothed itself over as the development and QA teams got into a habit of flagging, collaborating and reviewing documentation as part of an issue. 

Final remarks

For product teams, it is critical to factor in accountability into the document review process. A good documentation review is the best endorsement from the business and technical teams regarding the quality of documentation. Over time, you will find the review cycles get shorter, sharper and more focused.