When to update documentation?

["Geoff Hart (by way of \"Eric J. Ray\" <ejray -at- raycomm -dot- com>)" <ght -at- MTL -dot- FERIC -dot- CA>]

Joanne Tait (nice to see another Quebecois(e) on the list!) wondered
about updating the various types of documentation that accompany
software releases.

<<We are trying to define the tasks involved in a beta release.>>

Well, the first thing is to convince the powers that be to include
some documentation--any documentation--with each and every
revision of the beta. This is by far the best way to get early
feedback on your documentation. I get the impression that most
techwhirlers are in the unfortunate situation of not being able to
get any feedback on their docs until after the product ships. You
should set a new trend in your company!

<<when do you write a whole new manual or simply write an
addendum...?  Do major version numbers (i.e. v1.5 to v2.0) dictate
the need for a new book or is it the actual number of pages to be
rewritten/added that determines this?>>

I'm in the fortunate situation of documenting software with a very
small audience, so I can do short-run reprints of the documentation
in lockstep with the changing software. That same rule applies even
more strongly to online help, because the production costs and time
delays are effectively zero (i.e., no reprinting, and the help ships
on the same disk or CD as the software). If you're producing software
for a very large market, then economics probably becomes the main
deciding factor: every major (x.0) version released definitely needs
a full new manual, but in between, it's going to depend on what you
can persuade your management to accept. From a user perspective, it's
probably best to get an entirely new manual with each release, since
then you don't have to juggle 23 half complete manuals when you're
looking for something. Ideally, new features are added in modules, so
you can produce a mini-manual on that topic alone; realistically,
things are never this simple, and you usually have to pick your own
sticking point at which to reprint.

<<Read Me file:  a text file that accompanies the executable
installation file (that is, not compiled in install .exe file) and
contains installation instructions>>

That's pretty much the standard definition, but it's a lousy paradigm
for shipping software. My definition: A Read Me file is something
that only about 1% of the users ever read, and then only after the
installation doesn't work. I can't see any reason why the
installation program itself shouldn't display the read me file as
part of the installation process, thus preventing users from avoiding
the file. (For example, I've seen installation programs that warn me
to turn off my antivirus software before proceeding; I've also seen
the same warning only in the Read Me file. Which one is more
effective?) Can you persuade your programmers to do this? Again,
since you're developing a documentation procedure from scratch, this
is a great opportunity to do it the right way instead of the
traditional way.

<<Release Notes:  a text or pdf file that addresses  concerns
regarding knownsoftware bugs and describes fixed bugs from earlier
versions and workarounds>>

Sounds reasonable, so long as the existence of this file is clearly
advertised during the installation process _and_ in the "getting
started" manual. If you ship a pdf file, make sure you include the
appropriate version of Acrobat Reader on disk, and instructions on
how to install it (including a warning to check for more recent
releases of Reader first). Otherwise, you're producing a file that
many users simply won't be able to use.

<<Addendum (to the manual):  documents minor changes to the existing
documentation (i.e. a new button on a dialogue box, etc.), and any
errata(e/s/um(s))>>

Sounds reasonable.

<<Revision (to the manual):  documents major revisions to only one or
two isolated sections of the manual (does not effect the entire
manual)>>

Yes, provided everyone agrees on what constitutes "major" revision.
Don't count on getting that agreement easily.

<<do you update the on-line help for each release or only for major
ones?>>

Always ship the latest help file, since there's no reason not to.
Excuse me... there's one good reason, and that's if you do a major
overhaul of the help file and don't have time to do a thorough debug
(e.g., checking for broken links, missing graphics, etc.). In that
case, put the new information in a printed addendum. But if you can
possibly persuade your marketeers that a one-week delay won't
bankrupt the company, try to arrange for that extra week to debug the
help file. To steal an old trick from techwr-l, why not hold a
one-day debugging party to celebrate the shipping day? Bring in pizza
or cookies and offer rewards to anyone who finds a bug by day's end.
--Geoff Hart @8^{)}
geoff-h -at- mtl -dot- feric -dot- ca

"Men are from Earth. Women are from Earth. Deal with it."--Author unknown

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=