SUMMARY: Communicating obscure product changes

[JGREY <JGREY -at- MADE2MANAGE -dot- COM>]

Thank you to everyone who responded to my question, which was: Have you
had success communicating obscure product changes without needlessly
cluttering your manuals or ballooning your "readme.txt" documents?  I
received plenty of ideas and I'll be applying elements of many of them.

-----
I was especially surprised to hear from a tech writer working for one of
my company's customers.  DArsenault -at- atn-microwave -dot- com wrote:

We are users of Made2Manage here at ATN Microwave. I write ATN's docs. I
rely on the search capabilities of windows help to get users to the
bottom of obscure stuff. The only good paper analog is the index. I do
not personally use M2M, but I see the folks here who do carrying around
your books.

-----
Dick Margulis (ampersandvirgule -at- worldnet -dot- att -dot- net) had outstanding
suggestions:

1.      If you already know which customers are using the affected
feature
(because they are logged in your customer support database), call them
or email them specifically with an alert that the product's behavior has
changed with respect to their tasks. This can be done by the support
person who logged the call in the first place and win huge good will for
your company.

2.      In the release notes, begin with a one-page summary, with a
clean and
easy-to-read table that has the following columns:

        Sequence number
        Brief title (same as subhead later in the release notes)
        You are affected if you ...
        See page no.

The third column, of course, is the important one; and you should write
it as carefully as you write anything anywhere in your documentation. It
should be absolutely clear, concise, and brief and should leave no doubt
about whether I as the user need to review that item in detail or can
safely ignore it.

I don't mind getting thirty pages of release notes if I can see at a
glance that the only items that affect me are on pages 19 and 27.

-----
Beth Agnew (bagnew -at- insystems -dot- com) wrote:

We run into these same issues, as we also deal with relational
databases, reporting, and document management systems. Many of our
customers are clever enough to build their own workarounds for the odd
bug they might find, but in the meantime we work to correct these
errors. As in your situation, once we fix the error, then the customer
gets a surprise, unless we let them know what the impact of the change
might be.

We have found that for a small number of errors, putting them in the
readme is fine. A few fixes that affected the majority of our customers
_were_ put into the documentation in sections such as "What's New in
Version X.1", or "What's Changed from Release X.0". But for a long list
of obscure fixes, we have decided to put that info on our website. We
are in the middle of revamping our website, but we plan a technical
updates section where patches can be downloaded, and where FAQ and other
technical information such as our fixes list can reside. We also plan to
have an exclusive URL and probably password protection so that we can
restrict access to bona fide customers. In the readme, we'll include a
recommendation to check the website for more information.

-----
Chris Hamilton (chamilton -at- gr -dot- com) wrote:

On the really small, esoteric things, like you describe, we don't try to
make
the solution available to everyone. Generally, something like that will
result
in a support call. So, when we work out the bug, the support guy will
handle it
with the customer, then we'll do a technical supplement. These are
generally a
page or two. When they are finished, they are put on the corporate FTP
site.

The product for which I'm describing that is at the end of its
lifecycle. We
have another product which is a lot bigger and about to be born. The way
I
intend to handle that is to use the same basic structure, but publicize
the
technical supplements more. The new product is much more expensive and
will
have a smaller install base, so I can see us having a mailing list of
contacts
and telling them that technical supplements x, y, and z have been added
to the
FTP site if they're interested. We'll probably also add them to the
on-line
documentation. It's going to be done (eventually) in HTML using
JavaHelp, so
adding a few pages here and there isn't going to hurt.

If they're that small, though, I don't see us adding them to the printed
documentation.

-----
Elise Kaplan (ekaplan -at- asaint -dot- com) wrote:

We document dozens of such changes with each distribution of our
software.
I agree with you, these nitpicky issues are tricky to document in a
comprehensive documentation set, as a rule.  However, I think you can
often
make a case for including them as an "alert" type of note, just for the
sake of the user who is combing the documentation to determine why her
custom report run over INMAST is producing strange results.  This is the
situation in which your doc truly adds value to the product, as well as
avoiding a hotline call or a complaint.  Unfortunately, a chapter that
is
riddled with "important" notes and "gotchas" is no picnic to sit and
read
through, but I'm the only person who really does this anyway --
everybody
else just skims through till they find the particular piece of
information
they want.

For our release notes, we do is try to document each change clearly and
concisely, and what we hear is that our customers read these notes much
more avidly than they do our reference set.  In fact, our users can't
wait
to get their hands on each set of release notes and distribute them
promptly to key staff in their organizations.  We also include the
release
notes on our secured customer web site.  We can't count on each of our
customers applying each update promptly upon receipt, so it helps to
have
previous release notes available for a year or so.

-----
Joy Prescott (joyp -at- loronix -dot- com) wrote:

We publish that kind of information in a special technical bulletin that
we send out to customers. If there is a series of steps involved, we may
publish an addendum to the manuals.

-----
Keith Arnett (keith_arnett -at- reston -dot- omd -dot- sterling -dot- com) wrote:

     Are your developers using a change control system, such as
ClearCase?
     If so, a change documentation methodology should be automatically
     enforced (as developers generally must enter comments concerning
their
     changes).  With this done, your only decision is, "Will this change
be
     of interest to the end user?"

     If your development lab is not using a change control system to
     document changes to the software <shudder>, then you might consider

     meeting with the developers and designing some sort of separate
     in-house document for recording changes to the software.  That way,

     everyone's happy.

     And, look on the bright side: at least your developers are keeping
you
     in the loop regarding product changes!

     For our products, small changes like the ones you describe are
     documented for in-house reference only.  The information is
     communicated to individual customers when and if our customer
service
     department gets a call concerning that particular issue (this
assumes
     that the change is more or less transparent to the end user).

     In this case, the customer is given a patch to resolve the problem,

     and documentation on installing the patch.  However, unless there
is a
     specific "need to know" on the customer's part as to how the patch
was
     executed, this information is not generally included.

     Including README files with our software is a rare exception,
rather
     than the rule, and then it is usually with a patch, where a README
     file is the most efficient way to document the patch.  We do
include a
     "What's New in This Release" section in our user manuals, but this
is
     strictly feature oriented.

     I have worked on products where an ever-growing README file was
     included with the release.  With each new release, new information
was
     inserted into the top of the file.  This made for an interesting
(and
     lengthy) chronological history of the product, but had little
interest
     in terms of functionality to the end user.

     For major product releases, I prefer to limit README files to
     user-pertinant last-minute changes or additions to the product that

     came too late to be included in the standard documentation set.

-----
Again, thank you to all respondents.

Peace,
jim

jim grey \ Documentation Manager
Made2Manage Systems, Inc. \ jgrey -at- made2manage -dot- com