[no subject]

[Daniel P Read <danielread -at- JUNO -dot- COM>]

>>>>>>>>>>>>>>>>>>>>>>
For those of you who write version release notes, do you refer back to
the parts of the manual affected in the release notes themselves? Do
customers find this helpful? Distracting? Do you think it's a good idea?
<<<<<<<<<<<<<<<<<<<<<<

Release notes are a double-edged sword.  On the one hand, they work
pretty well for existing users who are upgrading from the previous
version.  If this proverbial user is the type of person to read at all,
they are likely already familiar with the manual, and the release notes
benefit them because they need to know what is different about what they
are accustomed to.  I can't see manual-chapter refs hurting in this
instance, but may or may not be of great benefit.  You might even say
that it is wasteful to send this existong user a whole new manual.  With
a whole new manual, how is the existing user to find out what is
different without wading through the whole manual and comparing it with
the old one?  Of course, over several upgrades, this existing user may
wish to get a whole new manual, because what he has is a manual from four
revs back and a big stack of release notes.

The release notes sword cuts the other way, however, with the new user.
If you have release notes, have you also updated and reprinted the
manual?  If not, the new user is stuck with having to search through
different sources for the information she needs.  Not good, especially
over a few revs.  Plus, the screen shots and field descriptions in the
manual no longer match the actual software.  In this case, not including
chapter references in the release notes would be irresponsible at best.

There are two compromises to this dilemna: one, make your print
documentation modular and distribute it in a three-ring binder.  Then,
when something changes, send the new pages with instructions about where
to place them in the binder, and what pages to remove (if any).  This
works pretty well, but assumes the users are diligent enough to keep up
with it.  Plus, in a corporate environment, even if there is someone who
is diligent enough to update the manual with the new pages, there
potentially may be dozens of users in the company who are now stuck with
the problem of having to wade through the whole manual to find out what's
new.  The other problem here is that documentation modular enough to lend
itself well to this approach tends to suck.

Compromise two is to switch to 100% online docs.  This is what our
company did recently, and it has worked out great.  We converted all of
our print documentation (a manual from three revs back and three sets of
release notes) to hypertext and included a version history section so
that users could find out what has changed since the version they are
most familiar with.  It's worked out great.  The only release note we
send with our upgrades now is one that tells users how to access the
online docs and how to use the version history.  Our help desk call flow
has gone down by more than 25%.

Summary, IMHO: if you must use release notes, I would recommend including
the chapter refs, but also refs to other release notes, or maybe even
incoporate some kind of feature history into each feature change in the
release notes.


Daniel Read
danielread -at- juno -dot- 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