Learning the fine art of reviewing

	Gurudutt Kamath

If you asked me what the most painful part of being a technical writer is, my answer would be: “Getting reviews on time. Getting good feedback and inputs on your work.” For me technical writing has been very pleasurable because I hardly got any review comments. My morale has therefore been very high. Project managers, developers and others are so busy trying to come up with good software (read trying to fix all the goof-ups and bugs!) that they usually tend to give documentation lesser importance. User manuals, who reads them anyway? We do not have time for it!

However, increasingly we have excellent project management these days. Documentation is a part of the project plan. Time is allotted to it. Similarly, time is allotted for reviewing. So life has become quite simple.

If I may make a confession here, I have never bothered about reviews. I just remind the people a couple of times that I have not received their comments/inputs. If I don’t get them, so be it. I feel it is their responsibility. “If review comments are not provided within 24 hours, it will be assumed that the document is correct and accepted.”

Troubled reviews

One of the biggest problems of reviewing is that the reviewer does not know what he/she is supposed to review. For instance, they tend to correct the English. I am not denying the fact that we all may make some typographical or grammatical mistakes. But this is not the main goal of reviewers. English is to be reviewed by editors and technical writers. Mercifully, nobody has made a punctuation correction in my documents for a long time now (apparently, my punctuation skills have improved!).

The main goal of the reviewer is to find out whether the documentation is complete. Is it in sync with the software? Is it true to the software? In this increasingly complex world, software creation is quite demanding (given the extremely short time to market). The software developer does not know the domain (say, Chemistry or Shipping); the domain expert (say, customer support executive) does not know the software technology.

It is quite possible that the developer is developing one small part and he/she does not know the other parts. So in a user manual, the small part documented and reviewed may be accurate, but it may not be exactly what the software delivers.

This problem can be solved by having everyone in the project team review the documentation. This will serve two purposes. Everyone will be in sync with what they have developed and the documentation will be complete and accurate.

Experienced technical writers write in such a way that the gaps in the documentation are invisible. Typically, this happens when a module or a segment has not yet been developed or is not complete. The technical writer writes what he sees, but what the customer gets is something else altogether.

The customer support executive and the developers may have a lot of information. However, they fail to communicate this to the writer. They fail to understand what information the customer wants. It is ideal for the technical writer to know the customer intimately. Customer support executives could provide valuable clues as to how the customer thinks and behaves.

In fact, customer support executives should behave like internal customers and think like customers to find faults/gaps with the manuals and the help files. Or, to give this a positive spin, find ways to improve the manual.

Reviewing should not be looked upon as a faultfinding mission. It should be teamwork with a goal—to deliver a useful piece of communication to the customer. If the communication succeeds, the team succeeds. If it does not enthuse the customer, the communication has failed.

Tips for reviewers

• Use the Tracking feature of Word to make changes. Whatever text you add, delete or modify is highlighted in a different format. This makes it easy for the technical writer to understand the changes and make them. Many a time, I just open the document, review the changes and simply accept them.
• Use the Comments feature of Word to add comments and questions. The technical writer can simply hover the mouse over the highlighted yellow area to read the comments shown in a yellow box (like a tool tip).
• Read the document at least twice. Once to have a quick overview. Next, to go over it minutely.
• Concentrate on the big picture and goal. Is the document really delivering in terms of its objectives?
• Give the review on time or ahead of time.
• Give the review in one whole piece (and not in parts).
• Avoid hand-written reviews.
• Be specific. Do not be vague. Comments like: “Is this true?” “Is this correct?” are not useful. “This module does so and so and works like this, this, this,” is useful.
• Try and give some positive feedback. The hard work that technical writers do may not be obvious to you. If you appreciate their work, you can expect even better results next time.

24-hour cool down

This is a luxury that we technical writers do not have—a 24-hour cool down period. When you write a first draft, keep it aside for at least 24 hours. Review it again after a day (24 hours). You will be able to spot many more errors and give a squeaky clean document.

For corrections, have a 1-hour cool down period. If you have corrected something, review it after an hour. If it is okay, only then send it to others.

Gurudutt Kamath is a technical writer based in Mumbai. Feedback on the column may be sent to documentor@vsnl.com