I’ve long been a student of technical document reviews. So much so, I worked as technical reviewer for some computer book publishers to learn more about this critical element of the technical communications development standards (and that 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, but oh so many organizations fumble through the review cycle unnecessarily.
- No Process. I stopped being surprised years ago about how often that organization’s don’t know how to review their technical documents effectively even when they have a technical writing group.
- 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 to keep them on task so the document they are reviewing meets organizational/client expectations.
- No Ownership. Just like other parts of the process, somebody needs to own the document review cycle whether it is a project manager or a technical writer 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.
- The “Idiot as a User Advocate” standing in for the writer, editor, or reviewer. Knowing your audience and the technology being documented is critical to a document review. While there are still those hold out technical writer is only going to cause havoc on a writing project unless they can separate what they don’t know about the topic versus what the audience doesn’t know and needs to know. 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 as the reviewer can only focus on what they themselves don’t understand versus the intended audience of the document who may indeed be more technically savvy and astute than the reviewer.
Image by freeimages.com user: deboer
Will Kelly is a technical writer and analyst based in the Washington, DC area. His writing experience also includes writing technology articles for CNET TechRepublic and other sites. Will’s technology interests include collaboration platforms, enterprise mobility, Bring Your Own Device (BYOD), project management applications, and big data. Follow him on Twitter: @willkelly.
Originally published at willkelly.org on September 8, 2010.