Re: Software version numbers

[Len Olszewski <saslpo -at- UNX -dot- SAS -dot- COM>]

[...]

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

[...]

> 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?

This depends how your release structure works.

We have versions, and releases within versions. Versions are the major
thing, releases are, generally, platform specific.

Our primary documentation (the big reference, usage, ref and usage,
examples, syntax, etc.) is all geared to versions. The library
architecture is such that for all products, the names are similar, like

SAS Language: Reference, Version 6, First Edition

Releases occur within versions (for the past several years, at least,
and this technique looks like it will stick). So our release 6.08, for
example, was for OS/2 and Windows platforms. Our release 6.09 includes
SOLARIS, ULTRIX and RS/6000 platforms. Release 6.10 is a different set
of platforms.

For changes to a product introduced within a release, that is between
versions, we issue technical reports wiith all of the "changes and
enhancements" by product by release. We have to say the release number
on the cover.

At the version level, platform differences are documented in
platform-specific "comapanions". So you get the primary doc (with all
portable platform-indendent features) identified with version number,
the companion for your host platform identified with version number, and
the changes and enhancements reports, identified with release number
(assuming you upgrade, which you should, you know 8-).

Other discretionary formal documentation is typically done at the
version level (though not necessarily). Technical reports, which treat
selected topics that discrete groups of users say they need, are
typically done at the release level. Many times, material provided in
tech reports become part of formal documentation for the next version,
but not all the time.

That's how we do it here. Sorry you asked, I'll bet. Provided, of
course, you are still awake 8-)E). <-----(my attempt at a smiley grin,
sometimes I feel creative)

How you identify your documentation depends in large part what meaning
your company attaches to the releases. We provide maintenance updates to
fix bu...er, software *anomalies*, but there isn't any formal doc there,
just instruction on how to apply the patches (we call 'em "zaps"), and
usage notes from tech support indicating potential problems and
solutions (by zap number, no less). We do maintenance releases on a
regular cycle, by release.

I won't get into the experimental/beta/production distinctions, since I
would bet Yankee dollars that no one really cares.

There it is, numbering in a nutshell.

|Len Olszewski, Technical Writer |"I may be banal, but I'm not        |
|saslpo -at- unx -dot- sas -dot- com|Cary, NC, USA| juvenile." - Yours Truly           |
|---------------------------------------------------------------------|
| Opinions this ludicrous are mine. Reasonable opinions will cost you.|