From TechWriter Wiki

Jump to: navigation, search



Reviews may be performed against the first draft, against the finished communication, or at any point in between. Which drafts will be reviewed, by whom, and for what purpose (see Types of review) should be clearly specified in the terms of reference or documentation development process.

Types of review

There are essentially three types of document 'review':

  • Textual review (a review of style) - these are covered under Editing;
  • Expert review (a review of content) - these are covered in this section;
  • User review (a review of usability) - these are covered under Usability testing.

Purpose of the review

The 'expert review' is largely a content review. The purpose of this review is to ensure that the document is technically accurate and complete, and is fit for purpose.

  • May be formal, resulting in sign-off (that the document is suitable for publication or release);
  • May be by a peer, by technical experts, by a document review board, or by the person, company, or organization that commissioned the writing of the document.

Having your work reviewed by others

The most effective reviews are reviews conducted by people other than the author. An individual author will be 'too close' to a document to subjectively review it. Furthermore, people are very bad (if not incapable) of identifying their own errors.

When asking another person to review a document, you must be absolutely clear about what is expected of them, and in what timeframe. It is not sufficient to pass the reviewer a document and ask "Can you check this for me?". Some things to consider are:

  • Explain the type of review that they should perform. For example, should they be reviewing the document for technical accuracy, suitability for the identified audience (and tell them who this audience is), grammatical accuracy, conformance to styles & standards, and so on.
  • Explain the way in which comments should be fed back to you. Are handwritten annotations on a hardcopy sufficient, and if so should they use formal proofreading markup? Or should they update the document themselves, online, using revision tracking?
  • Explain the entire review process to them: let them know their position in the review chain (especially where there are several reviewers all reviewing different aspects of the document). Clarify whether they will get the chance to review the corrected document. Consider allowing them to opt in or out of the next review cycle).
  • Specify the date by which their review comments are expected.
  • Make sure the reviewer understands if and when they need to formally approve ('sign off') the document, and explain what this approval represents. (Sign-off is often useful for professional indemnity.)

Could provide a checklist, but these only really work if the person is willing to make several passes through the document - once for each checkmark. Otherwise they will review everything all at once and then just tick all checkmarks at the end, regardless of whether or not they have specifically checked the entire document for each point.

Don't bother including a big list of instructions with every document, as it won't be read. If possible meet with the reviewers at the start of the project and explain it all then. Try to avoid making demands, such as "Do not simply mark the draft with a question mark" - use words such as "Try to provide clear comments so that the author does not need to return to you for clarification."

Make sure drafts are distinguishable - include draft numbers and/or dates). On re-reviews make sure you return their original comments (where applicable) along with the corrected document so they can check you have made the requested corrections. Use revision tracking where possible (especially on long documents where they may not want to review the entire thing all over again).

Reviewing the work of others

Make sure you know what they want you to check

Providing feedback - bear in mind that most people don't understand the 'standard' review marks - usually clearer to just cross out texts and write new text above or in the margin (unless you specify/explain the standard marks at the start of the project).

Cycling documents for re-review

Once you have made the requested changes, it is normally a good idea to re-submit the document for review, to the same reviewer. This will allow the reviewer to validate the changes, and also provide them with the option to make further changes. There is a temptation to discourage reviewers from making compound updates, but ultimately it will result in a better publication.

When submitting documents for re-review, consider attaching the reviewer's annotated copy (from the previous review) to the new copy. If you have declined to make any of the requested changes, then it is wise to provide an explanation of why on this copy. This will save the reviewer thinking you have missed an update, and marking the same change again. If documents go through multiple review iterations, then it is normally only necessary to attach the last copy reviewed and not all prior copies.

Working with multiple reviewers

In some cases, a document may be reviewed by multiple reviewers in parallel. This raises additional considerations. The first problem comes with incorporating these comments into the document. With six reviewers, there is the option of editing the document six times, once for each reviewer, or of editing the document once, juggling six annotated copies at the same time. Both methods are not without problems, but both are manageable.

The bigger problem is where different reviewers make conflicting edits. Here, it is necessary to contact the reviewers and ask them which update should be made. This can put the writer in a difficult position, at best acting as an arbiter, and at worse acting as a conflict buffer. Clearly, it is in the interest of the writer to ensure that the correct edits are made, but it is normally best to stand back and let the reviewers sort it out themselves. Consider review meetings where all reviewers sit around a table and go through all of the suggested changes to reach consensus.

With multiple reviewers, it is even more critical to submit the document for re-review, to all reviewers. Although this will undoubtedly result in further work, it is essential that each reviewer gets to see the amendments made by all other reviewers.

Incorporating review comments

  • If you don't include comments, you need to go back to the reviewer and explain why;
  • If you have conflicting comments from different reviewers, you need to mediate;
  • Once you have incorporated changes, you (personally) need to re-check the entire document (and not just the changed sections) to ensure that it still flows correctly, that the logic of exposition has not been compromised, that there are no discrepancies, etc.;
  • Depending on the level of changes, you may need to re-circulate for review.
Personal tools