A review of The Review
A key part of writing instruction manuals is asking clients to review and comment on a draft of their documentation. This can be an onerous task for reviewers who are busy with their main job, which will rightly take priority.
Having recently re-designed our website, we found ourselves on the client side of the review process. This gave us valuable insight into the questions faced by reviewers.
- How do I review? What is the best way? The quickest way?
- What software should I use to review the documentation?
- What content exactly do I need to review so I don’t waste my time?
- How much detail does the author require to understand my comment?
- How much creative freedom do I allow the author?
- Is that an error or does the author know something I don’t?
- Should I list everything in one go or will this overwhelm the author?
The first basic issue encountered is how best to communicate our comments. This is something we have thought about constantly over the years. Our go-to method for many years was to request changes using MS Word Track Changes so they had an audit trail. However not everyone is familiar with the feature and as we move away from Word versions of manuals it becomes less practical.
There are several software options that contain a document review feature:
- MS Word Track changes
- Adobe Acrobat Comment tool
- Dropbox Comments feature
- MadCap Flare Contributor
- JIRA
- A less familiar but specific review software
Each option has its benefits but also all have drawbacks.
The approach we often take is to give clients the freedom to choose their own method of review. This flexibility is to not tie the reviewer into a piece of software they are unfamiliar with, and over time we may see a consensus in the way clients choose to review documentation.
Documents being reviewed in sections, with comments being drip-fed over a period of time usually leads to poor results. This can happen when a reviewer is pressed for time, where reviewing is a shared task, or if the document is large and therefore the review process exceptionally long.
The result of this type of reviewing method is that it becomes difficult to plan the actioning of comments, due to the sporadic nature they are arriving and the unknown quantity of comments that need actioning.
Actioning comments piecemeal is inefficient, the ‘pick up and put down’ nature of the task means time is wasted setting-up and refamiliarizing yourself with the document. There is also a danger that comments conflict or one of two get missed. This method of reviewing slows down the project, either through its innate inefficiency, or because if we can predict this is happening, we will wait until the flow of comments has ended before processing them.
In a perfect world, a document will be reviewed in full as a single task and result in a single set of review comments, to be neatly worked through in a planned way, with comments being ‘ticked off’ as they are addressed. Then followed up with a final draft giving the client the option to repeat the review process, before the documentation is finalized.