Sharp Words

As mentioned in my post about the documentation process, there are two types of review which your technical documents should ideally be put through. 

Technical Reviews
Technical reviews should be done by a subject matter expert (SME) - in other words, someone who knows all about the technical thing you’ve written about. In practice, this is usually the engineer who built the item or the developer who wrote the software, or maybe a tester or member of the customer-facing technical support staff. If, as happens a lot with my documents, a new section of document was written in response to a request by someone within the company, it’s a good idea to get them to review it too.

You might have more than one SME involved in reviewing the document.  If appropriate, flag the review copy for each reviewer so that they don’t waste time reviewing something they don’t know much about - they’ll thank you for this, believe me!

Generally, any review comments about the technical contents of the document must be applied - after all, your reviewer is the expert. Of course, if you disagree with changes they’ve suggested, or you’ve had conflicting suggestions from different reviewers, it’s always best to get clarification.  Dealing with review comments is something I’m going to cover in my next post in this series.

Peer Reviews
A peer review is generally done by another technical writer. If you’re working by yourself (perhaps for a small company, or on contract), then you need to find someone with a good grasp of grammar, who also knows about how to structure information and how to use a style guide (assuming you have one).

Your peer reviewer should be checking for:

• general readability - in other words, does the order and wording of the information given in the document make sense to a reader and user?
• writing issues - grammar and spelling problems
• adherence to any style guides - it helps if they’re familiar with the usual format and formatting of the documents you produce

Changes suggested by a peer reviewer are frequently subject to debate - for example, you might think one way of wording something is more appropriate than the way they might prefer. As mentioned previously, dealing with review comments is something I’ll tackle in my next post in this series.

Very often, your technical reviewer will check for these types of things too. It’s a good idea to tell the SMEs beforehand whether you want them to look for such issues or not. I’ve had plenty of review comments back from SMEs where they’ve spent a couple of hours correcting the wording in a document (even though that wording was dictated by the style guide) but without spending any time looking at the technical content they were supposed to check!  Also make sure that your reviewer knows what they’re supposed to be looking for - and if they only need to check a small section of the document, either give them just that part or flag it up for them.

————–
If you have any questions or comments about this article, or any suggestions for future posts, please comment on this post or email me via my contact form.
Technical Writing Tuesdays: index of posts