I’ve long been a student of technical document reviews. So much so, I worked as a technical reviewer for some computer book publishers to learn more about this critical element of the technical communications. Back then I thought I could do a better job than the reviewers where I was working at the time). Editorial and technical reviews are integral parts of the technical publications process. Unfortunately, so many organizations fumble through the review cycle.
1. No Process.
I stopped being surprised years ago about how often organizations don’t know how to review their technical documents. Having or not having technical writers on staff has nothing to do with poor technical review processes.
2. Reviewer Likes vs. Standards
We all have our own likes and standards when it comes to writing. All document reviewers need clear and well-documented guidelines for the review cycle. Such guidelines keep reviewers on task.
3. No Ownership
Like other parts of the process, somebody needs to own the document review cycle. The project manager or the technical writer should be the owner and track the progress of the review cycle. The owner of the review cycle No Accountability.
There needs to be a level of accountability for both the writer(s) and reviewer(s) to shoot for the highest level of technical accuracy they can achieve within the constraints of the documentation projects. Development teams and technical writers can build in tools for achieving better technical accuracy through such means as technical writer access to test environments, fostering a culture where it is OK and acceptable to ask constructive questions.
4. The “Idiot as a User Advocate”
Knowing your audience and the technology being documented is critical to a document review. The Idiot as a User Advocate technical writer is a tech industry myth. Avoid them at all costs.
Editors without a grasp of the technology can also hamper the document process by introducing in technical accuracies instead of making appropriate queries and questions to clarify anything they don’t understand.
Having such a reviewer at the end of the document development process can also be counter productive to the review. They’ll only focus on what they themselves don’t understand not what the audience needs to know.
What does a technical document review cycle need to be successful?