Roughing it Out with Reviewers

By Geethashree Haridas

End-user orientation, domain knowledge, language usage, and presentation are the key attributes of good documents. But for documents to be truly worthwhile they should include these, and the most important aspect—content accuracy. Content accuracy is critical because inaccurate content serves no purpose and could be detrimental in use.

Unfortunately, perceptions such as “who reads those documents anyway”, “non-engineers”, and one of the worst— “just typing” still exist. How can we make reviews more effective and gain acceptance from these reviewers?

I feel effective reviews require a two-fold effort—setting the right expectations with reviewers, and communicating appropriately. In this article, I have tried to put forth my thoughts on the following broad topics:

• Defining the review process
• Different types of reviewers
• Some Dos and Don’ts

Defining the Review Process

Defining the review process is the first step towards setting the right expectations with reviewers. This ensures that reviewers provide inputs and share information with writers throughout the documentation cycle.

• Identify Reviewers
  Choose reviewers such as Product Managers (PMs), Development Managers (DMs), QA Engineers, or Developers, who understand the significance of documentation. The benefits of having PMs or DMs as reviewers are that they provide accurate information. They have first-hand technical information including the latest design documents and other sources of information. They can also assign resources to conduct reviews and help you with your day-to-day queries.
• Develop a Project Plan for Documentation and Publish It
  Identify the key stages of documentation and the review milestones. Formalizing the documentation project plan has a huge impact on the review quality. Reviewers are more serious about conducting reviews when a formal project plan for documentation exists.
• Involve Reviewers Early in the Cycle
  Involve reviewers right from the beginning of the documentation process to ensure that discrepancies are identified early. Involvement of reviewers in the early stages helps you to understand the product better. Reviewers also feel more responsible for the documentation being produced.

Reviewer Types

NOTE: This section is not the standard for classifying reviewers. I have created these reviewer types based on my experience.

Ideal reviewers understand the documentation function, guide writers, and give valuable inputs throughout the documentation cycle. They voluntarily share their pool of information with writers. They answer queries, and when something is wrong, they not only tell writers what is wrong, but also tell them why it is wrong and what they should do to correct it.

Unfortunately, not all reviewers are writer-friendly. They often fall into one of the following categories or a combination of categories.

Hello! Is Someone Out There?

Reviewers belonging to this category rarely respond to writers’ queries. It is a challenge to invoke responses from these reviewers.

How to handle them:

If you depend mostly on e-mail for communication, then this won’t work with these reviewers. Apart from sending e-mails, you should visit them personally or call them. Never send them trivial e-mails, because they will get convinced that they are doing the right thing by not responding. Consolidate your queries and send them in a single mail. For trivial queries, contact them personally.

Everything is Fine (But Always?)

This category of reviewers responds to writers, but always says the content is of excellent quality. It’s great if your document is picture perfect. But do your reviewers ignore your documents and say “Fine” just to keep you happy?

How to handle them:

This category of reviewers generally wants to respond, but finds it cumbersome to review documents. Draw the attention of these reviewers to specific issues. Send them a list of questions when you send your document for review. Highlight your doubts in the document and keep asking questions.

Nothing is Fine (Always Again?) and Do as I say

Another extreme of extremes, this is the nitpicking category. They think that writers have written it all wrong. They nitpick even on editorial issues, and often say things like “language is not crisp”, “overview is not business like”, and so on. They also believe that writers write to sell products and often mistake technical writing for marketing communication.

How to handle them:

This is the most difficult category of reviewers and rarely can you manage them without involving your manager or someone senior. When they say that something is wrong, ask for the exact explanation and justification. Educate them about your writing guidelines. Most important, escalate issues to your manager early in the process.

Too Many Cooks Spoil the Broth

When multiple reviewers review a document, writers may find it difficult to correspond with them. With this arrangement, one reviewer may assume that the other reviewer is doing the job. Reviewers may sometimes “pass the buck”. They may also give contradicting review comments.

How to handle them:

Minimize the number of reviewers. Ask your manager if these many reviewers should review the document. Make one of the reviewers your Point of Contact (POC) for easy communication and for resolving contradicting review comments.

Some DOs and DON’Ts

• Ask for directions when required, but DO your homework—before you start writing, before you ask trivial questions, and before you send documents for review.
• Be assertive when you ask for product demonstrations and other clarifications.
• Escalate issues early. If reviewers are being unreasonable, then inform your manager about it at the earliest.
• Respect the reviewers’ time and give them space. Remember that your reviewers also have other responsibilities.
• Gain the reviewers’ acceptance. Make the document useful for reviewers themselves. Give your suggestions to enhance that look and feel of that UI. Share your documents with the new Engineer who wants to learn about the product.
• Don’t accept flak from reviewers unnecessarily.
• Don’t send half-baked information.
• Avoid excessive communication.

Conclusion

Reviewers form an indispensable part of the documentation process, and writers cannot do without them. Writers should make reviewers understand the importance and impact of documentation reviews. Tools, knowledge, and writing skills do enhance the profile of a writer, but writers can go a long way if they know how to “rough it out” with difficult reviewers. Handling reviewers is an art. Know your reviewers, demonstrate your capabilities, and build healthy professional relationships. Communicating and responding appropriately is the key to resolve most of the issues.

(Geethashree Haridas is a Technical Writer with the CRM Group at Oracle India Pvt. Limited, Bangalore)

STC India | Home | Contact Us

© Copyright 2005, STC India chapter. All rights reserved..