Sharp Words

A lot of the suggestions in this article will depend on how well you know your reviewers.  If it’s their first time reviewing your documents, or you have a professional relationship with them rather than a friendly one, then you may need to compromise on more of the less important matters. Stick to your guns on the ones that you really care about though!

If your reviews have been done properly, you should receive two types: a technical review and a peer review.  Let’s discuss the technical review first, as it’s easier to deal with.

Technical Review Comments
In general, you won’t be the technical expert; whoever has reviewed your document should be. So, it’s a simple matter - take their suggestions for changes and updates, and apply them.

Of course, you might have described behaviour you yourself observed, or you might have conflicting comments from two or more technical reviewers. In these cases, you need to make sure that the corrections are, well, correct. Talk to your subject matter experts (SMEs) again; show them what you did and make sure that the software or hardware really is supposed to work like that - if it isn’t, someone may need to raise a bug!

Peer Review Comments
These can be harder to deal with as they apply to your writing itself. If it’s a spelling error or a formatting correction, go ahead and fix the problem. But if your reviewer has suggested changes to the wording or structure of the information in the document, you may need to think about them.

And it’s all too easy to think ‘well, I’m right’… and even if you can see their point, it’s easy to take this kind of review personally. Don’t. As discussed in the guest post by Roberto Villegas, Taking Bad Reviews Like a Pro, you can’t please all of the people all of the time, and what you think might be grammatically correct and structurally sound, another reader might not. It’s also very easy to get too close to your own work. Take a step back and assess it as your reviewer might have.

Sometimes, of course, your reviewer will just be wrong. Ignore their comments if you want, but bear in mind that if you submit the document to them for review again, they’ll just flag up the same stuff.

It’s far better to discuss the review comments with the reviewer where there is possible conflict - and this also applies if, as I mentioned can happen with technical reviews, you’ve had conflicting comments from reviewers. Be polite. Ask why they wanted something changed - good reviewers will have already said why in their review comments, but most won’t. If you think your way is better, be prepared to explain yourself. And be prepared to compromise.

————–
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