— Sridhar Machani
As a technical writer, it is not enough to document something and send it out for reviews. You must take the ownership of getting your work reviewed and incorporating the inputs from reviews. Getting your reviews done is a common challenge and, thereby, a pet excuse for the lack of accuracy and quality in documentation.
This article discusses tips to help you optimize the review cycle by managing your deliverables (organization, format, content), time (deadlines), and stakeholders (developers, managers).
Deliverables
1. Collate related docs.
A project often impacts several documentation deliverables or several chapters in the same deliverable. When you’re about to send excerpts, think about how best you can collate them so the reviewers don’t have to search for new or modified sections, or, worse, spend time thinking why the documentation is spread all over the place.
A useful approach is to name and attach the excerpts of impacted sections in a logical order (page, chapter, deliverable), and explain each attachment (metadata – sequence, the functionality it covers, page numbers and so on).
2. Send MS-Word format along with PDF.
Most publishing systems have capabilities to generate documentation output in PDF, HTML, and Word formats. Reviewers would find it easier to include their comments in a Word file, rather than copy-paste each item of content into e-mails and share their comments against each item.
It would also make sense to include references (links) to the complete deliverables, so that the reviewers can refer to them to better understand the context of the new or updated documentation.
3. Mark the sections.
You can mark the exact sections that were added or modified so that the reviewers can visually find the sections quicker. Typically, change bars are used in the case of PDF outputs. If your editor prefers to mark the editorial notations on printed paper, why don’t you print the sections yourself and strike out the irrelevant content before handing them to the editor?
Timeline
A best practice would be to share your documentation plan with the stakeholders. It should contain each deliverable and the estimated date of completion of each stage. Get it approved and address any concerns before you begin your work.
4. Provide enough time for review.
Enough said.
5. Fix deadlines.
In your communication, mention and highlight the last date for sending review comments. Your documentation plan should match these deadlines.
6. Send reminders.
We all need them and so do the reviewers.
Stakeholders
The teams of project and product management, subject matter experts, test validation, services and technical support are usually the stakeholders. Identify the key stakeholders who need to be included in all communications, especially in the progress and status of the documentation.
7. Include all the stakeholders; do not broadcast.
For each communication, it can be tricky to decide the list of senders from a group of stakeholders. One thumb rule is to decide whether they need to know the information you’re trying to convey. For example, you probably don’t need to include the managers when you’re sending a document for technical review.
8. Live review – initiate a working meeting with stakeholders.
When a topic of documentation is likely to generate conflicts (accuracy, scope, relevance, location in a deliverable), or is likely to cause a delay in its review, setup a teleconference with all the key stakeholders and get them to review the topic ‘live’. This is sometimes called a working meeting, and works best to resolve outstanding issues and concerns. Be prepared to moderate the discussion and get all of them to agree on a common decision. Disclaimer: use this sparingly and with caution.
9. Keep managers in the loop; escalate if needed.
There would be some topics or deliverables that get deadlocked, when nothing works and things seem to be beyond your control. That is the time to engage your managers who could use their experience and authority to get things done.
10. Build confidence.
Be prompt in addressing the review comments. The next time you send your documents, the reviewers know that the time they spend on reviews is not wasted. More often than not, they would be open to more queries from you.
About the Author
Sridhar Machani is a Technical Writer at Wipro Technologies. In his spare time, he doubles up as a Web design and branding consultant. He spends most of his energy at http://sridharmachani.com.
This is a test message.