How to manage a project documentation review

So the first revision of your document is now all written. Before sending it to your customer or your supplier, it can use a peer review to check its content. Let’s see how we can manage such a review.

Disclaimer

This article continues the description of a documentation process started by the following posts:

• Reading sheet, an easy tool for collaborative review
• How to organize your project documentation (naming convention, storage location, order…)
• How to build a Request For Proposal

This current article can be read independently but we will refer to those posts all along.

Why review a document?

The most obvious reasons are misspellings, everybody does them. But there are countless other good reasons to review a document:

• Peer review
• Check the consistency of its content.
• Check its clarity to be understandable by most people
• Make sure the document matches its purpose
• Check the layout
• …

The review process

A document review consists in several steps that require to be planed ahead.

Finding the reviewers and scheduling the reviews

Depending on the available collaborators for this specific task, it will be more or less difficult to have several reviews for the document. That is why we have to identify those reviewers before starting the redaction of the document and if possible schedule the reviews and the reviewers in the project planning.

On the other hand, having too much reviewers would lead to a big amount of similar remarks to manage which is very time consuming and pointless.

We recommend to have a maximum of 3 reviewers. Here they are from the most to the least essential:

• A peer reviewer
  It is an absolute necessity to have the document reviewed by someone understanding the technical content. This reviewer can check if the document makes sense, is consistent and describes something doable.
• A manager
  When the project manager doesn’t write the documentation he still should review it from a corporate point of view. Because he can tell whether the document content is qualified to be communicated out of the company (no confidential information) or not. Besides he knows the project big picture and can tell if the content matches the mandatory scope.
• A quality expert
  It is literally the icing on the cake because not all the companies can afford a “quality service” that ensures the deliverables to match the company standards. This reviewer will check everything but the content: graphical identity, layout, workflow compliance, spelling, etc.

Now that the reviewers have been identified and the reviews scheduled in the project planning, the document redaction can begin.

Freezing a revision for a review

The first draft of the document is done. The author considers it ready to be reviewed. Then he must freeze a document revision so the reviewers can read a stable revision that won’t evolve during their reviews. To do so, the author has 2 possibilities:

• He can work on something else and not reopen the document before all the reviewers have finished to check it.
• He can create a copy of the document. The reviewers will do their reviews on this stable copy. And the author will be able to independently take the reviewers remarks into account, on his original copy of the document.

We recommend a mix of those 2 ways:

1. The author creates a PDF of the draft document ready to be reviewed. This makes a stable revision impossible to alter for the reviewer so the author knows exactly what is reviewed.
2. In the project repository, the author creates a folder for this specific document revision and put the PDF in (see our article How to organize your project documentation (naming convention, storage location, order…).
3. The author sends an e-mail to the reviewers telling them the document is ready to be reviewed, where to find it and he attaches a blank reading sheet. This reading sheet is where the reviewers shall put their remarks.

The review

Every reviewer gets a frozen revision of the document and a blank reading sheet.

They list all their remarks in their own reading sheet : questions, misspellings, inconsistencies…
All those remarks shall be precisely located in the document and clearly described. See our article about the reading sheet to know how to fill it.

Taking the remarks into account

Managing the reading sheets

It is either the author who gathers all the reading sheets the reviewers sent him by mail, or the reviewers who save themselves their reading sheet in the shared folder next to the reviewed document revision and then notify the author. It is better to keep all the reading sheet next to their associated document to ease their management.

It is also easier for the author to wait for all the reading sheets before starting to update the document. Two reviewers can raise similar remarks on the same topic, so to avoid this, it is easier to analyze all the remarks at once before beginning to take them into account.

But sometimes the deadlines require the workflow to be sped up.

Analyzing the remarks

If there are several reading sheets to manage, gather all the remarks in one unique reading sheet, then sort them according to their location in the document, then the analysis can start.

The author will check every remark to:

1. Identify the duplicates and keep the most detailled one.
2. Identify the remarks that he will be rejected because they are off topic in his opinion. To do so he has to explain why in the comment section of the remark.
3. Sort the remarks to order their management: he may want to deal with the quickest ones first or he may need some more details with some others.

Updating the document

Once the analysis is over, the author reopens his working copy of the document and he can begin to take into account the remarks.

First, he adds a new event in the evolution table which can be “Updates due to the reading sheet <insert the reference>” and for more details he can add the list of every item to be updated. He can also add the reading sheet in the bibliography table of the document.

Then, one by one, he takes every remark into account and updates the remark status in the reading sheet accordingly.

Closing the remarks

It is up to the reviewers to tell if a remark has satisfactorily been taken into account and so declare it closed. So once the author has managed them all, he has to send the updated reading sheets and the new revision of the document to the reviewers. For each remark, if the reviewer is satisfied, it can be closed. If he is not, the discussion continues until they find an agreement.

When all the remarks are closed, then a new revision of the document can be frozen and sent to a customer, a supplier or any final recipient.

Conclusion

A document review is essential to ensure its consistency and a high level of quality. It is not an harmless activity, it shall be anticipated and scheduled in the project planning.

The reading sheet is a very helpful tool to structure the process. It allows it to be focused and keeps track of every evolution of the document. Such an history is a huge asset for any project from the simplest to the most complex one.

One last advice, when there can be only one reviewer (because of a small team, a lack of time, etc), we recommend this reviewer to perform 2 different reviews in this order:

1. A consistency review to check that the content is technically correct
2. Then a quality review only dealing with misspellings and layout.

This way to sequence work with separated reviews may prevent unwanted sidetrack on pointless topic for the project.