While maintaining technical documents can be the most boring part of the technical writer’s job in some organizations, it’s a necessary part of the business especially in policies and procedure driven environments.

However, updating documents often falls down the list of priorities and becomes a reactionary task versus a natural element of business operations. Becoming a reactionary task leads to such a simple task being flubbed and lapping up more resources and operational budget than first thought.

I see more smaller contracts now for writers to come in and update technical documents especially policies and procedures guides and got to think how I like to update documents:

Preliminary setup

Use track changes. Even if you are only using a single technical reviewer for your document(s), it is best to use Microsoft Word’s track changes for inputting edits and comments. It’s works even better if you make sure everybody involved in document reviewing has their name and initials filled in under Tools>Options on the User Information tab. Using track changes enables everybody involved in the document review to see who made which edits and comments. Track changes makes it easy when you need to track down a commenter for clarification on a comment.

Use SharePoint or another collaboration platform. Email and the Outlook Inbox are, unfortunately, traditional document management tools in some organizations that double as the workflow for document reviews. While sending documents back and forth is often times “baked in” to teams, putting documents into a SharePoint document library or on another document management or collaboration platform helps to lock down document versioning and ensure that everybody involved in the document cycle is using the same document.

Consider a document version history in the document front matter. If you are reviewing technical documentation, you may want to consider a document revision history page in the front matter of your documents if you don’t already have it in place.

Review

Conduct a document audit and initial edit. It’s easy to sit around a meeting table and poke holes in a document that you are seeing for the first time. What I like to do first is get a feel from the document owners what they see as the strengths and weaknesses of the documents. Then I ask questions like, “What is the freshness [age] of the document?” and “What issues in the document standout?” After seeing where my line of questioning takes me, I then like to do a first pass edit to take care of the big stuff.

Question and comment. Years of working as computer book technical reviewer taught me how to write clear and substantive comments. It’s important to drill into technical reviewers (especially the new ones) that their comments need to be constructive and if a technical fact is wrong that they should provide the information to make the correction.

Open a dialog with the author(s) and/or document owners. It’s easy to treat document technical reviews as solo efforts when, in fact, an open dialog can work wonders at review time. Encourage an open dialog between the author and reviewers and

Post Review

Use a central repository for documents. Get the documents off people hard drives and out of their secret stashes so they are secure but accessible to project team members, stakeholders, and customers.

What I’ve outlined in this post is a basic framework that needs to be adjusted to fit the requirements, resources, and schedule of a given organization and project.

What are your tips for updating and revising technical documents?

Image by stock.xchng user: tomdavies

Originally published at willkelly.org on November 27, 2011. This post has been revised prior to republishing it on Medium.

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.