software version numbers

[Susannah Skyer <susannah -at- SCO -dot- COM>]

Hi Kendal,

I work for a Unix operating system company and we indicate document
version and date on the title page of every manual, including release notes.
We also include a date at the bottom of all reference manual pages ("manpages").

We have major releases (eg, 3.2.4) and interim releases (eg, 3.2.4.2)
and we only do complete doc recuts with the major releases. We specify in
the interim release notes which doc has been recut and leave the customer
to assume that the rest of the doc remains current (but updated by the
relnotes).

The doc version number relates to the product version number, so, for example,
the second rev of our Unix System Administrator's Guide for the 3.2.4
main release would have the doc version number 3.2.4B. This lets the customer
know that the doc goes with 3.2.4 and provides a point of reference for
bugs/questions.

I see no point in updating otherwise unchanged doc to include a new date;
in fact, that would be somewhat misleading, because it would suggest that
the doc had changed in content since the last release.

So ... if I were you, I would:

- make sure I always had a date and a product version on the release notes
and any other doc you release (the product version tells the customer which
product you're talking about and the date provides a unique reference
for the doc itself)

- say in the release notes which doc had been updated (if any) for the
interim release, or include a blanket phrase like "Information in these notes
supercedes User's Guide information"

- agree a version numbering scheme with your developers (and whoever else
needs to participate) that can work logically for both software and doc
(ie, if the revs they're making to the software do not warrant a doc recut,
then perhaps these version should be considered "interim" or "point releases"
and the numbering scheme should indicate that. That way, you can have a
manual version 1.0 that goes with all 1.x products and so on.

- in terms of tracking changes (when you actually go back to rev the
main documents based on what you doc'd in the release notes), I wonder if
there's a way you could write a shell/awk script to compare the text
of the main manual to the text of the release notes and report, for example

"section 1.2.3 - editing forms -- mentioned in release notes"

Hope this is somewhat helpful,
Susannah Skyer
SCO

(PS. my favorite sports are tennis and running, and my next holiday
will be in Guatemala or Mexico)

------------------------------------------------------------------------------
Date:    Mon, 22 Nov 1993 10:42:07 MST
From:    kendal stitzel <kensti -at- KENSTI -dot- AUTO-TROL -dot- COM>
Subject: Software version numbers

Hi, netters.

I work for a company that makes a variety of UNIX-based software products.
[insert marketing brochure here]

Lately, some of our software developers have been agitating to get us to
include the software version numbers with our manuals. In the past this
has been handled by sending out a letter with the software and (sometimes)
update pages for the manual.

Obviously, it`s nice for the user to have the most recent software version
number printed on the manual.

The problem for us writers is that the company sends out a LOT of different
updates and most of these do not require update pages to the documentation.
We're already swamped and would rather not have to update zillions of title
pages. (We use FrameMaker and Frame doesn't send out update pages; we find
this quite annoying sometimes, having to dig up the release notes to make
sure something has or hasn't changed.)

But enough whining. How have some of y'all dealt with this issue? Do you
send out updated title pages with software version changes? Do you trust
your users to track these changes with Release Notes? Do you not have this
problem at all and prefer to discuss sports or holiday plans?

Just curious.

Ken Stitzel (not that other guy)
low-writer-on-the-totem
Auto-trol Technology
Denver, Colorado
(kensti -at- Auto-trol -dot- com if you prefer e-mail)