Lead Writer: Felicity Brand, Kieran Morgan | Peer Reviewer/s: Steve Moss | Managing Editor: Kieran Morgan

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
Table of Contents: Technical Writing Process
Previous: Chapter 19: Edit Drafts	Next: Chapter 21: Validate and Test Information

1. Introduction

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.

Tip

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 or 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

An essential element of a successful review is knowing how to give and receive feedback diplomatically and graciously. In this section, we explain the ins and outs of good review etiquette. This section goes beyond the immediate requirement for document quality and focuses on establishing a long-term relationship of trust and mutual respect with your colleagues.

Tip

Be Respectful of Your Reviewers Reviews can take a lot of time out of someone’s busy schedule, so make the process as easy as possible and don’t make unreasonable demands. Consider making large review tasks smaller by breaking big documents into chunks (for example, on a chapter-by-chapter basis) that can be reviewed independently. Build relationships with your reviewers by remembering common courtesies such as thanking them for their time. If you’re not planning on making a change someone has suggested, tell them about it. They need to know that you’re taking them seriously and respect their contribution. If you don’t respect their feelings, they won’t put in the effort the next time you ask.

4.1. Receiving Feedback

It’s important for you, as the writer, to be prepared to take a step back from your work during review. When you receive feedback, take a deep breath and try not to take it too personally. Although it may sting to receive a critical review, once you recover from the blow to your pride and get down to the business of revision, you’ll be able to use that feedback to make your document better. Even bestselling authors heed advice from their editors and consider them invaluable partners in the writing process.

Here are some examples of effective and ineffective responses to feedback.

Not Effective

Effective

• Ignoring feedback: Dismissing feedback without consideration, for example, out of a desire to meet deadlines. This approach prioritizes timeliness over quality—almost always a mistake in technical documentation. • Defensive response: Taking critical feedback as a negative reflection on your overall skill set rather than your document’s accuracy and quality. The best writers understand that everyone can benefit from a different perspective.

• Objective analysis: Evaluating feedback based on its merit, not on the tone or the person giving it. Accepting feedback as a reflection on the document, not a general comment on your skill set. • Collaborative clarification: Engaging in respectful dialogue with the reviewer to understand their perspective and clarify any misunderstandings. Gently guiding them toward the best way to give you value-adding feedback.

Here are some techniques to help ensure that you make the most of review feedback:

• Maintain perspective: Recognize that feedback is aimed at improving the document, not critiquing you personally. A critical review is an opportunity for growth, not a reflection of your competence.
• Evaluate with openness: Consider each piece of feedback objectively. Even if the delivery is less than diplomatic, the underlying point might be valid.
• Verify technical details: If feedback involves technical changes, verify the accuracy with relevant sources or consult with another subject matter expert to ensure consensus.

Engage in dialogue: If you’re unsure about a comment or feel it’s based on a misunderstanding, engage in a conversation for clarification. This can lead to a better understanding of the reviewer’s perspective.

• Document decisions: Keep a record of feedback and your responses, such as comments in your authoring system or a Review Log Template. This not only helps in tracking changes but also in explaining your decisions to the review team.
• Acknowledge and thank: Always thank reviewers for their time and input, regardless of whether you implement all their suggestions. A polite acknowledgment of their effort fosters good working relationships.

4.2. Giving Feedback

Reviewing another’s work can add tremendous value to a document, but it can strain the relationship if the review isn’t performed in a sensitive manner. Even if a reviewer doesn’t intend to—in fact, even if all their review feedback is completely accurate—they may cause offense simply due to the way their feedback is phrased. Aspire to be both a gracious recipient of feedback and a diplomatic giver of it and your relationships with your peers and colleagues will thrive.

Here are some examples of poorly and well-phrased feedback.

Poorly Phrased Feedback	Well-Phrased Feedback
“Your introduction is confusing and lacks clarity. You need to rewrite it.”	“The introduction has some great ideas, but it might benefit from a bit more structure to guide the reader through the concepts more clearly. Perhaps an outline of the main points could help?”
“This section is too technical. Simplify it immediately.”	“I appreciate the technical depth in this section, but it may be a bit complex for beginners. Could we consider adding some introductory explanations or simplifying some of the technical terms for accessibility?”

So, what went wrong? Both sets of comments are essentially conveying the same points, but the poorly phrased comments are written in a hurtful way that’s not constructive. They also don’t offer concrete solutions, just negative feedback.

To avoid the situation above, here are some general rules on giving a good peer review:

• Do it justice: Commit to reading and comprehensively understanding the document. Avoid merely skimming, as it might lead to superficial or inaccurate feedback.
• Note first impressions: Keep a record of your initial reactions as you review the document. These first impressions are valuable and can provide a strong foundation for your formal review. Technical writers are often the first users of a product, so your initial reactions will likely mirror those of the target audience.
• Guide with suggestions: Rather than issuing commands, guide the writer toward better practices with suggestions and questions, as illustrated in the examples above. This approach is effective whether you’re a colleague or a manager, as it nurtures the writer’s sense of autonomy, responsibility, and pride in their work.
• Acknowledge when you don’t know the solution: You’re not always going to have the answer, but identifying when something isn’t quite right can also be useful. For example, you could say, “I keep stumbling over this part but can’t think of any suggestions for how to fix it.”
• Be specific: Ensure your comments are clear and directly related to specific sections of the document. This is particularly important when responding via email, as opposed to inline comments within a document. In emails, it may not be immediately obvious which section you are referring to.
• Balance negative with positive: Always find aspects of the document to praise. A reviewer’s role is to be constructive, aiming to enhance the document. Acknowledging what works well is as important as identifying areas for improvement.
• Recognize you might be wrong: As a reviewer, present your feedback as your personal opinion rather than as a universal truth. Who knows, you might be wrong! For instance, a house style rule or technical detail you’re familiar with could have recently been updated without your knowledge.
• Follow up and engage: Encourage a dialogue with the writer after delivering your review. Offer to discuss any points that might need clarification and be open to understanding their perspective. This follow-up strengthens the relationship and ensures that feedback is well-received and understood.

5. [Practice] Review Draft

Now that you understand the importance of the different types of review, it’s time to get your documents reviewed.

5.1. Step 1: Define Review Team

If you haven’t already done so, you’ll need to define your reviewers and their responsibilities in a review matrix. Receiving a “Request for Review” shouldn’t come as a surprise! We discuss this planning step in detail in Chapter 12: Define Review Team, and provide a Sample Review Matrix to capture all the necessary information to prepare for a successful review: Chapter 12: Define Review Team | 4. [Sample] Sample Review Matrix. This helps you plan out your review in advance, ensuring it doesn’t delay your publication date.

Tip

Be Choosy about Your Experts It’s essential to have the right people review your content. A poorly informed subject matter “expert” can cause more problems than they solve. Make sure you’re reaching out to experts with a true depth of knowledge in the subject you’re documenting—and ensure they’re fully engaged in the review process.

5.2. Step 2: Validate and Test

Before you send your documents for review, make sure they’re validated and tested. This will catch errors and inaccuracies in advance of expert review, which will save time for your reviewers and reduce the number of review cycles required. It will also reflect well on your craftsmanship if you send out a well-researched document. In Chapter 23: Validate and Test Information, we showcase different methods for doing so. These methods vary in complexity and cost, and their application should be strategically timed—some before the subject matter expert review, some after, and others at any stage.

5.3. Step 3: Request Review

When it comes time for review, many folks fire off a hastily worded “Request for Review” email, attach their documents, and hope for the best. However, you can get much better results by acting as a guide for your experts. Prompt them into giving you good, value-adding feedback by explaining the aim, purpose, and mechanics of the review. This will help them focus on the areas that you want them to—and steer clear of those that you don’t want feedback on, such as grammar and punctuation.

When sending documents for review, frame the accompanying note with care to ensure the review team understands what’s required. Include the following:

• Context: It shouldn’t be a surprise to receive your request. However, if your experts are the kind of people who are frequently inundated with review requests, jog their memory with a concise précis of your document’s purpose.
• Timeframe: Include a clear timeframe by which a response is required. If you’re working in an Agile environment, earmark a particular sprint you’d like to receive the feedback in.
• Feedback mechanism: Specify how you’d like to receive their feedback. Should they use comments and track changes in an attached document? Or the review functionality of your organization’s authoring tool? Do they need to respond to a workflow request in a content management system?
• Review responsibilities: What are their respective responsibilities? Guide them to focus on their area of expertise so they can add the most value with the minimum wasted effort. This should be in alignment with the review matrix in your Documentation Plan Template.
• Option to approve: If they’re satisfied with the document as-is, how do they indicate their approval?
• Thank you: Thank them in advance for their time to show that you value their input and the time investment they make in reviewing your content.

See Sample Request for Review for an example of a well-crafted request for review. Use it as a template or for inspiration when you’re crafting your own request.

Insight

Comments vs. Markup Some writers prefer to request comments from subject matter experts instead of marked-up changes. Comments provide scope for detailed explanation, which you don’t get with markup. This lack of context can leave writers with more work as they chase up the intention behind a marked-up change. Also, track changes can quickly become unworkable if revisions from several reviewers need to be integrated back into a single document.

Note

Doc Reviews in a Docs-as-Code Environment If you’re working in a docs-as-code environment, your review mechanism with developers may be through a process known as pull requests (PRs) or merge requests (MRs). In this setup, documentation resides inside (or alongside) the code, typically in the form of simple text files. Developers use PRs/MRs to review and provide feedback on your content. They may directly edit the content or offer feedback through comments in the code.

5.4. Step 4: Chase Up Outstanding Review Tasks

A seldom-acknowledged aspect of being a great technical writer is learning how to be a persistent chaser. The most productive technical writers are almost always following up on review tasks, as they’ll often have multiple documents under review simultaneously. This may seem tedious, but it’s all part of the job description. Consider it an exercise in the art of diplomacy. Learn to be polite yet persistent, It’s a balance between ensuring timely publication and technical accuracy without causing undue friction among colleagues.

Here are some methods you can use to chase up outstanding review tasks, in sequential order:

1. First, see if reviewers respond within the timeframe. There’s no need to badger anyone before the timeframe has elapsed, unless you receive new information and the need becomes urgent.
2. Once the original timeframe for review has elapsed, immediately send a reminder note or email as a nudge.
3. If you haven’t received a response to your note within a few days, follow up with a phone call, a message on an internal messaging system, or a text message to their phone number. This is more personal—and harder to ignore—than an email. Be polite but clear—explain that the request is now urgent and holding up publication.
4. If you still haven’t received a response after trying all these methods, request assistance from your line manager or a project manager. Note the times and dates you tried the methods above, showing them the emails if necessary. They can then use their authority and relationship with the expert, or the expert’s manager, to apply the appropriate pressure.

Tip

Fallback Methods When You Just Can’t Get a Response What if you’ve tried everything and you still can’t get reviewers to respond? Unfortunately, this can happen. Here are some fallback methods you can use if all other techniques have been to no avail: • Review workshop: This is a technique for dealing with time-poor subject matter experts. It involves scheduling a short (typically one- or two-hour) workshop with a group of experts. As the facilitator, you walk the experts through the documentation on a shared screen. Don’t hesitate to ask questions or challenge parts of the document that seem problematic. Keep a record of the discussion and decisions made by using something like comments or sticky notes. This technique is excellent for yielding first impressions and identifying obvious errors, but don’t expect an in-depth examination. It works best for shorter documents, such as processes and brief procedures. • Endorsement by default: When you send out a review request for low-risk content, consider including a “default endorsement” clause, for example: “If no feedback is received by [date], I will assume your endorsement.” Such a statement clarifies what will happen if a reviewer doesn’t provide feedback. This approach can be helpful where you’ve thoroughly tested and validated content already and the review is more of a formality. However, don’t use this technique for high-risk content, like safety procedures, or high-impact content, such as user guides.

5.5. Step 5: Collate Feedback

Now that you’ve completed a thorough review and followed up on outstanding review tasks from your reviewers, it’s time to collate their feedback. If you use a system that aggregates all feedback in one place, excellent! You’ll save a lot of time, as the system has already done this for you. This functionality is common in many content management systems and authoring tools.

However, you may find that—for various reasons—you receive feedback in diverse forms. This is where a Review Log Template can be useful. This spreadsheet allows you to keep track of comments received, associate them with a specific version of the document, and monitor the actions you took to address them.

The Review Log is a valuable tool for consolidating feedback, especially if you receive review comments from different channels—such as email, sticky notes, written markup on hard copies, or verbal feedback noted down during the morning stand-up. It’s also helpful when managing a highly controlled document where you need to detail your response to every comment.

Tip

Strike a Balance between Organization and Efficiency With our passion for attention to detail as technical writers, it’s easy to get carried away with administrivia. However, there’s usually no need to log absolutely everything in your Review Log. Aim to strike a balance between the benefits of having a single source of truth for review feedback and the extra time it takes to consolidate and process all the commentary you receive.

What Does That Mean?

Feedback Any comments or markup received from a reviewer in a document review. Markup Symbols such as strikethrough and “red-line” that indicate changes to a document, such as additions, changes, and deletions. These may be written on a hardcopy printout or applied via the track changes functionality in an authoring tool or word processor. Comments Written notes about any aspect of a document. These may be specific to a section or paragraph within the document, or general commentary about the document’s overall effectiveness. These may be emailed as a summary, affixed to a hardcopy with sticky notes, or applied via the comments functionality in an authoring tool or word processor.

5.6. Step 6: Update Draft

Now that you’ve consolidated all the review comments, it’s time to update your draft document. Remember, review is a two-way street. It’s up to you, as the writer, to decide whether or not to accept the suggestions from the reviewers. Don’t take every comment as gospel; carefully weigh each comment on its merits before acting. Consider whether it adds to or subtracts from the overall usability of the document, and carefully validate any changes to technical details before implementing them.

5.7. Step 7: Close Out Comments

As you work through the feedback, note your response to each comment received and mark them as resolved. This way, both you and the reviewers know you’ve actioned them—even if it’s just giving a thumbs-up or marking it as complete. This approach helps you keep track of everything. If you need to write a response—for example, your rationale if you’ve decided not to action a comment—make your comments concise yet diplomatic, and ensure they’re archived somewhere visible to reviewers. Whether in a shared document or attached and sent via email, it will give reviewers the option to respond with further clarifications if necessary.

5.8. Step 8: Respond to Reviewers

Finally, respond to the reviewers with a brief thank you note. This can be as formal as an email or a brief note on an internal messaging system. Think of this as a gesture of your appreciation for the time and effort they’ve put into reviewing your document. It also involves them more deeply in an ongoing conversation about your document’s accuracy and usability. Although some folks won’t mind either way, it’s easy for people to feel offended if they think you’ve ignored their feedback, which will make them much less likely to contribute meaningfully to a review in the future.

6. [Sample] Sample Request for Review

Sample Request for Review

7. [Template] Review Log Template

Review Log Template