SUMMARY: Communicating obscure product changes

Subject: SUMMARY: Communicating obscure product changes
Date: Wed, 8 Apr 1998 07:53:06 -0500

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

1. If you already know which customers are using the affected
(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
the solution available to everyone. Generally, something like that will
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

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
intend to handle that is to use the same basic structure, but publicize
technical supplements more. The new product is much more expensive and
have a smaller install base, so I can see us having a mailing list of
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
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

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

We document dozens of such changes with each distribution of our
I agree with you, these nitpicky issues are tricky to document in a
comprehensive documentation set, as a rule. However, I think you can
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
riddled with "important" notes and "gotchas" is no picnic to sit and
through, but I'm the only person who really does this anyway --
else just skims through till they find the particular piece of
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
to get their hands on each set of release notes and distribute them
promptly to key staff in their organizations. We also include the
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
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
If so, a change documentation methodology should be automatically
enforced (as developers generally must enter comments concerning
changes). With this done, your only decision is, "Will this change
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
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
department gets a call concerning that particular issue (this
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
executed, this information is not generally included.

Including README files with our software is a rare exception,
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
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
inserted into the top of the file. This made for an interesting
lengthy) chronological history of the product, but had little
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.


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

Previous by Author: Communicating obscure product changes
Next by Author: JOB: Requirements Analyst/Writer (Indianapolis, IN)
Previous by Thread: Re: a UI question
Next by Thread: Beating a Temporary Retreat

What this post helpful? Share it with friends and colleagues:

Sponsored Ads