Re: Version Revision number

Subject: Re: Version Revision number
From: Beth Agnew <beth -dot- agnew -at- senecac -dot- on -dot- ca>
Date: Thu, 01 Dec 2005 15:57:32 -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 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:

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).

The plan currently states that the version number shall be incremented by one for significant
changes and incremented by 1/10 for minor changes.

The problem is lack of definition of "significant" and "minor". I'm afraid we will all go back to
the old ways (just add a version number and make up your own rules) without some type of
easy-to-follow guideline.

--
Beth Agnew
Professor, Technical Communication
Seneca College of Applied Arts & Technology
Toronto, ON 416.491.5050 x3133
http://www.tinyurl.com/83u5u

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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! http://www.webworks.com/techwr-l

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. http://www.componentone.com/TECHWRL/DocToHelp2005

---
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 http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


References:
RE: Help & Manual questions.: From: eva knodt
Version Revision number: From: Tara Charter

Previous by Author: Re: Visual Information books by Edward Tufte?
Next by Author: Re: The second person in user guides
Previous by Thread: Version Revision number
Next by Thread: what are you working on today


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


Sponsored Ads