Re: Version revision number

[Beth Agnew <beth -dot- agnew -at- senecac -dot- on -dot- ca>]

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 6.xxx 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.

--Beth

Tara Charter wrote: