Re: Version revision number

Subject: Re: Version revision number
From: Beth Agnew <beth -dot- agnew -at- senecac -dot- on -dot- ca>
To: "List,Techwriter" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 02 Dec 2005 19:15:31 -0500

What constitutes a revision? How often are revisions made? Are these internal revisions, or published to the customer? Change control is as important in documentation as it is in software development. We know that code has to be frozen at a particular build for testing, and shipping if it's ready to go. It is the same with documentation. As long as the document is still "open", being worked on and not yet finalized, approved, or signed off, its version is fluid. Do you add a revision number if you change the order of the chapters, or at the end of a day's composing? I don't. I say make all the changes you want without tracking revision numbers until you're ready to publish (get signoff). It's just a housekeeping headache to try to keep track of all those minor versions. I've never needed them, in many years of TW.

Occasionally, however, someone will ask for a chapter or huge section to be removed, and then a few months down the road, want it back in. If I am not using a version control system such as Microsoft Visual Source Safe for documentation, then I make a point of archiving my own files so I can go back to an earlier version if necessary, to get that chunk. A manual in progress might be filenamed Zabo6_1 to start off with. After any significant amount of work, I Save As and up the filename to Zabo6_2, Zabo6_3, etc. By the time we get to publishable version and approval stage, it could be Zabo6_49 or whatever, but that's a completely internal tracking number. All my previous files would be backed up on the server, and on a CD-ROM for safety.

I only release (republish) a manual (or suite of documentation) on a point zero release (6.0, 7.0, or 7.2, 7.5 if there has been no 7.0). I prefer to do manuals in editions, rather than version numbers. The Zabo 6.0 manual (with addenda if necessary) is still good for version 6.0.310 of the software. Users want to know that if they have version 6.0... of the software, the version 6.0. manual is what they should be looking at. When the developers plan to release a new build to customers, the documentation matches the release. If it's a minor release, just catching up bug fixes, then I publish release notes to draw the customer's attention to whatever is important. The release notes are then labeled Zabo 6.1. A patch, to fix a few customer problems, just gets a readme file with the build number of the software.

A more significant release, i.e., one in which there are customer-affecting changes, and perhaps even a couple of new features, say a 6.5 release, would rate publishing a Supplement. Then customers would have in their hands the Zabo 6.0 Manual, and Zabo 6.5 Supplement. Should a greater number of features be added, making an interim release still at the level, or -- heaven forbid! -- there are errors in the manual that need to be fixed, I may release a second edition of the Zabo 6.0 manual. I generally treat all corrections to published documentation as either bugs or requests for features, just as in software development. I determine if they are critical, important, minor or cosmetic, and assign a priority accordingly. The changes are made to the next release of the documentation, in the same way developers prioritize and implement bugs and features in the product.


Tara Charter wrote:

My company is updating its Documentation Plan. The plan includes guidelines for adding and updating
the Version/Revision number to the document (software development documentation).

Beth Agnew
Professor, Technical Communication
Seneca College of Applied Arts & Technology
Toronto, ON 416.491.5050 x3133


Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today!

Doc-To-Help 2005 now has RoboHelp Converter and HTML Source: Author content and configure Help in MS Word or any HTML editor. No proprietary editor! *August release.

You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.


Previous by Author: Re: The second person in user guides
Next by Author: RE: Project Management Office
Previous by Thread: RE: Version Revision number
Next by Thread: RE: Version revision number

What this post helpful? Share it with friends and colleagues:

Sponsored Ads

Sponsored Ads