Re: Version numbering

[Beth Agnew <bagnew -at- INSYSTEMS -dot- COM>]

On Monday, October 06, 1997 8:41 PM, Terence Kierans [SMTP:TKierans -at- TRANSIGO -dot- NET -dot- AU] wrote:
> I am having a difference of opinion with the Quality Manager.
>
> He maintains that versions should progress as integers, ie 1,2,3,4 etc
> regardless of the extent of the change.
> I am endeavouring to make minor changes as dot versions eg 1.1, 1.2,
> 1.3 etc, and reserve the integer change for major changes.
>
> Can someone please point me to a reference which I can quote for what
> constitutes "major" and "minor".

Terence,

I don't think it has anything to do with whether it's a "major" or "minor"
revision. Version control for user guides is different from that used
for software, and you have a number of options.

1. Do your manuals have to match a software release? Many of our
user guides must accompany releases of software, which may be
v4.7, v.5.3 etc. So that we don't confuse our customers, our manuals
have the same version numbers as the software. Internally, however,
we add an extra digit so that the third draft of our Release version 4.7
manual would be 4.7.(3). This is removed when the manual is approved
at final. (And we do more than user guides -- see below.)

2. Do you have an approval process?
We reserve integers to the left of the decimal for approved versions
of documents and use the integers to the right of the decimal to
track internal revisions between approval milestones. I'm currently
working on a manual that is version 2.2 because this is the second
revision since its last approval. (We use an iterative process here, too.)
When the manual goes for approval, it will be issued as Version 3.0.

We number _drafts_ for new manuals as 0.1, 0.2 etc. Once that
draft has received final approval, it becomes Version 1.0 of the
manual. We don't use "revision" as a title.

3. Do you track document revisions with version control software?
We use MS Visual SourceSafe thus we can keep track of even
minor revisions if we need to, without having to worry about
changing version numbers. It doesn't make sense to change the
version number if all you've done is a spell check, changed the
layout a little and updated the table of contents and index.

4. Do you have a publications management process?
With a formal process, we find that we revise less often, but
they are more substantive when we do. This ultimately saves
us time and headaches. It makes version control easier, too!

In summary, we make a distinction between "issued" (approved)
documents and documents in revision. We worry more about
the version numbers attached to the issued documents, and
whether they need to match released software. We track
minor revisions in SourceSafe, and manage the entire process
carefully.

--Beth

Beth Agnew
Senior Technical Writer, InSystems Technologies Inc.
65 Allstate Parkway, Suite 100  Tel: (905) 513-1400 ext. 280
Markham, Ontario, Canada L3R 9X1        Fax: (905) 513-1419
mailto:bagnew -at- insystems -dot- com    Visit us at: http://www.insystems.com

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html