This chapter focuses on the review phase in technical writing. It highlights the importance of peer, subject matter expert, and approver reviews in ensuring document quality. It covers core concepts such as review etiquette, including techniques for diplomatically giving and receiving feedback. The chapter also discusses practical steps for a successful review process and emphasizes the need for technical writers to skillfully manage reviews while maintaining strong working relationships with colleagues.
|Who Should Read This
|• Aspiring Technical Writers
• Beginner Technical Writers
• Cross-Domain Professionals
|Book Table of Contents
|Previous: Chapter 21: Edit Drafts
|Next: Chapter 22: Review Draft
Table of Contents
- 1. Introduction
- 2. [Theory] Write-Review-Update Process
- 3. [Theory] Types of Review
- 3.1. Peer Review
- 3.2. Subject Matter Expert Review
- 3.3. Approver/Document Owner Review
- 4. [Theory] Review Etiquette
- 4.1. Receiving Feedback
- 4.2. Giving Feedback
- 5. [Practice] Review Draft
- 5.1. Step 1: Define Review Team
- 5.2. Step 2: Validate and Test
- 5.3. Step 3: Request Review
- 5.4. Step 4: Chase Up Outstanding Review Tasks
- 5.5. Step 5: Collate Feedback
- 5.6. Step 6: Update Draft
- 5.7. Step 7: Close Out Comments
- 5.8. Step 8: Respond to Reviewers
- 6. [Sample] Sample Request for Review
- 7. [Template] Review Log Template
Imagine a writer. You might picture a solitary figure hunched over a lamplit desk, pouring their genius into a Great Work. This romanticized image, while traditional, misses the mark when it comes to technical writing. Technical writing is a highly collaborative process involving inputs from numerous people at every stage. In our world, writing is far from a solo pursuit—it's a team sport!
Nowhere is this more true than in the review phase. It's in this phase that the quality of technical content is ensured through review by numerous collaborators, plus a process of rigorous validation and testing. In this process, the writer acts as a conductor orchestrating the end-to-end process, chasing up recalcitrant reviewers, updating and editing documents, and managing progress and timelines along the way. Experienced writers often juggle numerous drafts at different stages of maturity simultaneously, masterfully guiding them through to completion without compromising on quality.
In this chapter, we explain the concepts behind a successful document review, from the nuts and bolts of the different types of reviews—peer review, subject matter expert review, and approval—to review etiquette, which is the art of giving and receiving feedback. This is critical to building good relationships with your colleagues. As we transition to Chapter 23: Validate and Test Information, we'll build on these concepts, focusing on validation and testing methods. These are crucial steps to ensure your documents aren't just well-written but are also accurate and user-centric.
By the end of this chapter, you'll be equipped with practical steps for producing high-quality, thoroughly reviewed documentation. Balancing quality with timeliness can be tricky, but with the right approach, it's achievable. So, let's get started on this journey to mastering the art of review in technical writing.
2. [Theory] Write-Review-Update Process
In our discussion of the write-review-update cycle in Chapter 19: Write Draft, we explored the iterative process of drafting documentation, reviewing it for accuracy, and ensuring its readiness for publication.
The diagram below illustrates a generic write-review-update process for a typical document. It’s a simplified view of the overall write-review-update process, omitting the loopbacks that can occur at any stage. Use this diagram to frame your understanding of the interplay of responsibilities among the writer, reviewer, and approver as you progress through the chapters in Part 7: Edit and Part 8: Review.
3. [Theory] Types of Review
In the sample review process above, there are two swim lanes: one for "reviewer" and one for "approver." In a typical document review, these broad-brush swim lanes break down into several unique responsibilities: peer review, subject matter expert review, and approver or document owner review. In this section, we'll explain the nuances of each.
3.1. Peer Review
Peer review is a critique of your work by a colleague within your organization—i.e., another technical writer. Peer reviews add significant value: writers can learn from their more experienced or knowledgeable colleagues, and the process helps to converge writing styles among a team of writers.
Rather than a subject matter expert review, which addresses accuracy, usability, and completeness, a peer review analyzes your work through the lens of best practice of your craft and within the context of your organization.
Key Aspects of Peer Review:
- Document structure: Is the document well-structured and logically coherent?
- Appropriate wording: Is the wording appropriate for the context and audience? Does it flow well?
- Correct format: Have you used the correct document template or format?
- Style guide compliance: Have you applied the in-house style guide?
- Terminology consistency: Have you followed the appropriate conventions for terminology, such as product names and job titles?
The output of a typical peer review is a marked-up document with comments identifying problem areas and offering suggestions for improvement.
|How to Pick a Good Peer Reviewer
If you have the liberty of nominating a peer reviewer, select one whose work you know to be of high quality and ideally someone who has been at the organization for a while. It’s even better if they’re familiar with the product or process you’re documenting. Experienced writers will bring valuable insights that will improve your document. If they’re unfamiliar with your project, make sure you provide them with enough context so that they can conduct a meaningful review.
3.2. Subject Matter Expert Review
The primary purpose of subject matter expert review is to validate your document from a technical perspective, review it for completeness, and determine whether it’s suitable for the intended audience. It’s not for pointing out typos, or errors in formatting and grammar. These should have already been addressed during the writing and editing stages.
You should also have made every effort to validate and test the documentation yourself before sending it for review. This maximizes the use of your subject matter experts' time by weeding out the most obvious inaccuracies. See Chapter 23: Validate and Test Information for more information.
Key Aspects of Subject Matter Expert Review:
- Technical accuracy: Does the document accurately reflect the technical nuances and complexities of the subject?
- Incorporation of updates: Have any recent updates or changes to product features or technical specifications been appropriately incorporated?
- Content accessibility: Is the technical content presented in a way that is accessible and understandable to the intended audience, without oversimplifying the core concepts?
- Clarification of ambiguities: Are there any technical inaccuracies or ambiguities that need to be clarified or corrected?
- Industry standards compliance: How well does the document align with industry standards and best practices?
- Consistency of terminology: Are all technical terms used correctly and consistently throughout the document?
3.3. Approver/Document Owner Review
The final stage in the review process often involves the approver or document owner—typically a manager, project lead, or department head. This review is vital as it ensures that the document aligns with the overall goals, policies, and standards of the organization. The approver's role is to provide the final seal of approval, confirming that the document is ready for publication or distribution.
Key Aspects of Approver/Document Owner Review:
- Alignment with objectives: Does the document support and align with the broader goals and strategies of the team, department, or organization?
- Compliance with policies and standards: Is the document in compliance with organizational, legal, and industry standards?
- Overall quality and effectiveness: Does the document achieve its intended purpose effectively? Is it clear, concise, and useful to its target audience?
4. [Theory] Review Etiquette