Latest posts by techwriter (see all)
- BOOK REVIEW: “Design for How People Learn” by Julie Dirksen - July 10, 2017
- 12 Top Characteristics of a Good Technical Writer - July 3, 2017
- What Are the Qualities of a Good Technical Writer? - June 28, 2017
Keeping track of the revisions you’ve made to a frequently updated technical or business document is important.
A document revision history table will save you a lot of headaches when it is time to send out your document for a review.
Reviewers, especially in hi-tech companies, are very busy people. They are usually SME (Subject Matter Expert) engineers, developers, product managers or the client who hired you to draft the document.
If the document is just a few pages long, then asking your reviewers to read the “whole document” and give you a feedback is not a big deal. No one will complain about that.
But imagine you’ve finished the fourth draft of a 2,000 page document with 250 tables and 360 figures. And you are asking your reviewers “to read” the whole thing and get back to you “as soon as possible.”
There are two big problems with such a demand.
1) In documentation business, there is no such thing as “ASAP.” Sometimes ASAP means “never.” Give them a concrete date and time when you expect them to finish the review. For example: “July 31, 2014, Thursday, 5 p.m.” Then make sure you track that deadline like a hunter. If possible, a day before the deadline, send your reviewers a reminder. Then after the time is up, send those who still have not returned their reviews a “gentle reminder” about what they were supposed to do.
2) Send your reviewers a Document Revision History Table so that they can see exactly what changes have been made to do document and focus only on those changes since all the rest is the same in the document. Such a review aid will save a lot of time on the part of your reviewers and lower the tension between you the writer and your ever-busy review team members.
A template for such a revision log should have a couple of columns and as many rows as necessary, each row devoted to a single revision.
Here is an example of a DOCUMENT REVISION HISTORY TABLE:
|ROW #||DOCUMENT & Version, Release or Build Number||REVISION DATE||REVISION DESCRIPTION||REVISION TRACKING NOTES|
|1||Cool-Eye User Guide, V.2.1.5||2/3/2012||ADDED a new section “4.1” about “Calibrating the Lenses” to Chapter 4 “System Configuration”.||Bug Tracker # 2365|
|2||Cool-Eye Installation Guide , Build 43||5/1/2013||EDITED the Glossary and ADDED two new items: “DDG” and “CB Porting”.||RE: PM email dated 1/4/2013|
|3||Terra-Eye Quick Start Guide, Draft 4, Release 1.0.2||12/9/2014||DELETED Chapter 3 “Importing Data.” ADDED two sections “5.2” and “5.3” to Chapter 5 “Post-Install Care”.||TW-1234|
You can include such a log with the document itself or provide it to your reviewers as a separate document.
Whether the end-users should see such changes is a decision you should make after discussing the issue with your client or the Product Manager. There is sometimes merit in being very transparent and letting your end-users know about the changes the document went through; and sometimes there isn’t. If in doubt, consult your management and/or the legal department regarding the different ramifications of sharing such revision history with the end-users.
But sharing the revision history with your reviewers is always a good idea and will bring you praise and earn you much goodwill within your company since such a list makes life easier for all involved. It’s the thoughtful thing that an experienced technical communicator would do without even being asked for it.