4 reasons why your document reviews aren’t working

kelly-brito-256889
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?
Photo by Kelly Brito on Unsplash

Published by

Will Kelly

Will Kelly is a technical writer living and working in the Washington, DC area. After years of contracting, he returned to full-time corporate job in 2016. He writes thought leadership content around cloud, enterprise mobility, and cybersecurity topics. Will's has written for Samsung Business Insights, Tom's IT Pro, TechBeacon, CNET TechRepublic, and other sites. Earlier in his career, he wrote technical documentation for end users, developers, and operations teams. His current areas of interest include multi-cloud solutions, mobile security, and managed services. Follow Will on Twitter: @willkelly.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s