Feature
Best Practices for Managing Technical Reviews
by Meghashri Dalvi
How often have you encountered quality problems because the review is insufficient? How often have you struggled to get in last-minute reviews and still make the deadline? And, how often have you wished for a perfect reviewer who gives good inputs on time and does not venture into choice of verbs or grammar?
Managing reviews is perhaps the weakest link in the process of creating a good and complete technical content—whether it's a user's guide, a technical manual, or a marketing document. The problem lies in the communication gap that always exists between the writer and the reviewer. The expectations are not set, the constraints are not elaborated and most importantly, the value of the review is not defined clearly.
A simple set of five best practices can help overcome these problems:
- Describe "what" is expected in the review.
- Define "who" will do the review.
- Determine "where" the review process goes in the project schedule:.
- Guide "how" to do the review.
- Close the review process properly.
1. Describe "what" is expected in the review.
Many reviewers face a dilemma of where to focus in a review. Explain what you are looking for, mainly the completeness and technical correctness of the content. Also, highlight your audience and the intended usage so that the review is properly aligned. Ask for specific points or clarifications wherever applicable and as weill as for general feedback, such as if figures are clear.
Then, explain what you are NOT looking for. Gently drop a hint that the grammar and formatting will be managed by you / peer writer / editor. That frees the technical reviewers to do what they do the best.
Some may still insist on use of specific words or formats. Do not ignore them. Check if these suggestions have any relevance, or if they are standard usage within the company and accept or reject the suggestion accordingly. Do not forget to acknowledge the reviewer's contribution.
For some reviewers, a huge document poses a daunting task and an opportunity to dodge it. This problem can easily be solved by highlighting the portions where you need their feedback. Providing a 10-page document with a few paragraphs marked for review, and the task suddenly becomes easy for them. Dividing the review items into smaller chunks has always worked for me.
Grouping the relevant items together for review is also effective. For example, a feature may get described in the user's guide, product brochure, API guide, and troubleshooting guide. If you pull all these bits together and form a smart document, it gets more appropriate and precise review, especially from project managers or senior analysts who have a complete and bigger picture of the project.
Over a period of time, you can convert these review guidelines into a formal procedure and include them in the process documents.
2. Define "who" will do the review:
Ownership is a big issue in any project and ambiguous or undefined ownership leads to major snags. Early in the project, identify the reviewers assigned and include the "review" task in their task list. Ensure that the progress on review is also included in the periodic status reports. Insist on correct prioritization of the review task. Highlight overdue reviews and get a firm commitment from the owners. For genuine difficulties, you may want to reassign the review or reschedule it. But, make sure that your document delivery date is also adjusted accordingly.
If this has not been the standard system in the company, you may need longer time to get this practice going. However, once you establish it, the review tracking will be much smoother and the bottlenecks much clearer.
3. Determine "where" the review process goes in the project schedule:
This practice may look tough to introduce, but it's worth every bit of your efforts. Include the review in the development cycle of the project, as well as in the development cycle of the technical documentation. You will need a lot of convincing and supporting facts to get the review process in. Make those efforts for a long-term benefit.
Having a rightful place in the cycle ensures formal budget of time and efforts to the review. The tasks also get routed correctly and along with the practice #2, clearly define ownership of the task. Once the reviewers have formal review assignment and allotted time, a major hurdle of getting review done is crossed.
4. Guide "how" to do the review:
We spend hours with writing or editing tools, and feel very comfortable with them. The reviewers, however, might be more comfortable with code writing (and Notepad!) and struggle with "how" exactly to get their comments across. Some choose to print the content and write comments by hand. Some open a separate document (or text file) and painstakingly put their comments against page numbers and line numbers. Some even put the feedback in an email.
To streamline the process of review, train reviewers in the review tools. Help them with the "Track Changes" feature of Word and explain how each reviewer can set different colors to personalize the comments. If available, Acrobat can be a great reviewing tool, too. If some reviewers are still not comfortable, put a simple spreadsheet-based system in place. Convince all the reviewers to use the same system for consistency and also for tracking the implementation of review comments.
5. Close the review process properly:
This practice may look minor or insignificant, but in reality this act keeps your reviewers happy and enthusiastic for the next review. Everybody likes acknowledgment and appreciation. Give it by replying to the reviewers with how many changes are accepted / rejected and why. Thank them when they provide feedback.
You can actually put the action taken by you in a column in the review spreadsheet. Or even add tiny "Thanks" / "Good point" type comments in the feedback document. Save the feedback of everybody and then make it available at some common location. It helps build a knowledgebase and a treasure of comments—some worthy a great applause!
****************
Meghashri Dalvi has combined her love of writing with engineering and management background to create a successful career in technical communication. She currently works as a Consulting Technical Communicator in India, and is pursuing her doctoral research in Management.