TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Software version numbers From:Jim Grey <jwg -at- ACD4 -dot- ACD -dot- COM> Date:Wed, 24 Nov 1993 08:39:26 -0500
From: kendal stitzel <kensti -at- KENSTI -dot- AUTO-TROL -dot- COM>
Subject: Software version numbers
The real Ken Stitzel issued from his keyboard:
>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.
<snip>
>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?
We include release level on every manual page, in a roundabout sort of way.
When I got here 4.5 years ago, our document revision tracking left us with,
say, SuperLayer User's Guide, Issue 6/A -- when the software was at release
3.3. *Everybody*, even the writers, found this confusing, because there was
no correlation between manual issue and software release. So we started using
the software release number as part of the manual issue number. Immediately,
without *any* explanation, dang near everyone caught on. "Oh, this is
the SuperLayer User's Guide, Issue 4.12/A. This must go with the 4.12
software."
When we began this practice, an incremental release (say, from 4.1 to 4.2)
meant major work to the manual. We were in a period of hefty changes from
release to release. But now that we're up to 4.12, about to go to 4.13,
the changes are minimal -- we spend more time in administration (printing,
approval cycle, making diskettes for off-site storage) than actually doing
any writing. My 4.10 MLA User's Guide, for example, required four measly
hours of writing plus two days of admin. We decided, then, to release new
manuals only when the accumulated changes made the development effort
significant. The company began delivering the most recent manual plus
usage instructions for added or changed features. This made life easier
on the technical writers -- but everyone else became very confused, despite
repeated explanation. "Why did I get a 4.10 manual with my 4.12 software?"
It just didn't feel good to the customer. Heck, even internal users were
confused.
Things are a bit crazy here now, but once things settle we want to revise
our general format. One of the things we will do is remove the infernal
issue number from the bottom of each page. Then, in those cases where we
don't update a manual, we'll issue a new title page (which has the issue
number on it) with a special note referring the user to supplied usage
instructions, and whammobammo, there y'go, there's your new manual. We
hope that will solve this!
jim grey
jwg -at- acd4 -dot- acd -dot- com
Terre Haute, Indiana - The Silicon Cornfield
