structured authoring

How to Design a Document Revision History Template

Štefan Štefančík at Unsplash dot com

Introduction

A document revision history template can help you to make sure that your documents are always up to date and error-free.

Designing a Document Revision History Template

1. Include the current date and time in your document revision history template.

2. Include the name of the person who made the changes in the revision history template.

3. Include a description of what changes were made in each revision, such as “word choice,” “formatting,” or “spelling.”

4. Include a link to any other files that were changed during that particular revision so you can find them quickly if needed.

Importance of Document Revision History

Keeping track of the revisions you’ve made to a frequently updated technical or business document is important in documentation business.

A document revision history table will save you a lot of headaches when it is time to send out your document for 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 feedback is not a big deal. No one will complain about that.

A Scenario for Document Revision History

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.

Problem 1

1)      In the 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.

Problem 2

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.

An Example

Here is an example of a DOCUMENT REVISION HISTORY TABLE:

Revision history

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. You can include such a log with the document itself or provide it to your reviewers as a separate document.

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.

(Copyright-free photo courtesy of Štefan Štefančík at Unsplash dot com)

RESOURCE

How to Write a Documentation Plan

MORE INFO

Key Concepts of Technical Writing to Create Great Documents
What is the Difference between Content Writing and Copywriting?
How to Write Cause and Effect Sentences and Paragraphs for Better Documents
How to Prevent Compounding Editing Errors
New Money-Making Opportunities for Writers
Technical Documentation Terms
Software Documentation Terms You Should Know As a Technical Communicator