Reviewing
Publishing wrong documentation
can have consequences.
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:
Self-review The writer checking their own work to ensure clarity, consistency and accuracy before sharing with others.
Subject matter expert review One or more SMEs checking the documentation for technical accuracy.
Peer review A peer checking the final draft for readability and flow, providing feedback from the perspective of the intended audience.
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.
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.
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
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.
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?
It's best to wait some time between the moment when you finished the draft and the moment you start the review.
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.
Since you have (hopefully) already had conversations with the SME during the research phase, the SME review should not uncover new information.
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.
- 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.
Sometimes SMEs want to have input on the grammar, tone, phrasing and structure of the documentation.
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.
Once the technical details are verified, it’s time to get a fresh set of eyes on the document.
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.
Once the review is done, you are almost ready to deliver, but you should still dedicate some time to an often-overlooked step:
- Testing. Sometimes it's extensive, sometimes it's just a spot check, but it's still a good idea to do it.
