---
title: Reviewing
slug: books/technical-writing/reviewing
createdAt: 2025-04-29T17:04:01.617Z
---

:::BlockQuote
Publishing wrong documentation

**can have&#x20;**<u>consequences</u>**.&#x20;**
:::

Messing up the guidelines for complicated machinery can harm operators. In software, a wrong step can lead to a system failure costing large amounts of money.

It's obvious why reviewing documentation prior to publishing is essential.

A good review process follows three steps:

::::WorkflowBlock
:::WorkflowBlockItem
**Self-review**
The writer checking their own work to ensure clarity, consistency and accuracy before sharing with others.
:::

:::WorkflowBlockItem
**Subject matter expert review**
One or more SMEs checking the documentation for technical accuracy.
:::

:::WorkflowBlockItem
**Peer review**&#x20;
A peer checking the final draft for readability and flow, providing feedback from the perspective of the intended audience.
:::
::::

::Image[]{src="https://api.archbee.com/api/optimize/fh9Kla9lm_P4ujQJfZyJC/OF5ASTlYgVJ4g8bBxNqfF_image.png" size="60" width="564" height="374" position="center" showCaption="false"}

***

# Self-Review

A self-review allows you to catch obvious errors and inconsistencies. Even if you did all these things during the research and writing phase, it's important to have a dedicated review phase where you read the documentation end-to-end.&#x20;

Even with good research and helpful SMEs, double-checking your information is critical. SMEs forget details, specifications are not updated, last-minute changes are introduced... and it's not uncommon for technical writers to actually uncover scenarios that no one had thought about!

The self-review phase can be split into reviewing technical accuracy and reviewing content and style.

## Reviewing Technical Accuracy

Even with a helpful and involved SME, errors can still slip through. You should always try to validate the documentation, to the best of your ability, by:

- Following the documented steps yourself in a test environment
- Testing commands and code snippets
- Cross-referencing information sources and flagging any discrepancies

## Reviewing Content and Style

Even if it's just a first draft, the document you send out for SME review should be as close to finished as you can make it. &#x20;

Ask yourself these questions:

- Did you follow the company style guide?
- Did you use consistent terminology?
- Does the structure align to the guidelines and is it easy to follow?
- Did you proofread and check for typos?

:::hint{type="info"}
It's best to wait some time between the moment when you finished the draft and the moment you start the review.&#x20;

The break will help you return to the document with a clear mind, allowing you to spot errors or inconsistencies you might have missed while writing.
:::

***

# Subject Matter Expert Review

Since you have (hopefully) already had conversations with the SME during the research phase, the SME review should not uncover *new* information.&#x20;

::Image[]{src="https://api.archbee.com/api/optimize/fh9Kla9lm_P4ujQJfZyJC/ASoFqytIv-KKeawKUn7CK_image.png" size="40" width="828" height="1061" position="center" showCaption="false"}

However, this is probably the first time the SME sees the documentation in its final structure. To ensure a thorough review:

- **Send the document out for review only after the feature is finalized or the code is frozen.**
  This ensures that no further changes can occur. (At least in an ideal world! You know your environment best.)
- **If you added bits and pieces of information in an existing document, point out the additions.**
  The SME needs to know which parts to focus the review on.
- **If needed, ask the SME to review the legacy documentation as well.**
  Sometimes the old documentation also needs to be updated to accommodate a new feature, and it's not always obvious to a non-expert.&#x20;
- **Encourage the SME to *really* check for accuracy.**
  Some SMEs tend to assume that, just because they gave you some information in the research phase, you understood everything. This is not true - technical writers may misinterpret, misquote or rephrase SME information in incorrect ways.

:::hint{type="danger"}
Sometimes SMEs want to have input on the grammar, tone, phrasing and structure of the documentation.&#x20;

This is not necessarily a bad thing - but remember that, when it comes to the documentation itself, **you** are the SME. Implement their suggestions if they make sense, but not if they go against the style guide or technical writing best practices.
:::

***

# Peer Review

Once the technical details are verified, it’s time to get a fresh set of eyes on the document.&#x20;

The type of peer you choose depends on the type of review you're looking for: you can ask for a fellow technical writer to check alignment to the style guide or you can ask a customer support representative to see if it's user-friendly enough.

***

# Next Step

Once the review is done, you are almost ready to deliver, but you should still dedicate some time to an often-overlooked step:&#x20;

- [Testing](docId\:FUVOPfYZCmrEVxg3ykS-Y). Sometimes it's extensive, sometimes it's just a spot check, but it's still a good idea to do it.

