Communicating obscure product changes

Subject: Communicating obscure product changes
Date: Mon, 6 Apr 1998 08:56:22 -0500


I'm struggling to solve a niggling issue. I hope you can offer

Each release of my company's software product includes a whole bunch of
bug fixes. Many of these fixes are obscure. For example, I recently got
this request:

"We should probably document this change in handling 0 values in INONHD,
since I know of at least one other user ... that uses a custom report
that expects to find at least one undeleted record in INONHD for every
stock record in INMAST. The new handling could result in no records in
INONHD for an 0 balance on hand in INMAST."

(INONHD and INMAST are two tables in the product's database.) This
change is extremely obscure -- it affects only users who have created
custom reports such as the one mentioned in the quotation above. The
number of customers who create custom reports is fairly small, and the
number who created custom report(s) that involve this issue is even
smaller, but whoo doggie do they need to know about this change because
their custom reports won't work anymore. Or worse -- the report will
still execute, but will list bad data on which the customer will make
business decisions.

There are at least twenty such changes in each release of the software.
One release not too long ago had over a hundred database tweaks like

I turn down requests to "put this in the documentation." First of all,
in a nine-hundred-page doc set, it'd be the needle-in-the-haystack
problem, except that the user doesn't know there's a needle to look for.
Second of all, we write instructions for performing tasks in the
software, not encyclopedias of disparate product facts.

We've been adding this information to the software's readme.txt and its
printed counterpart, "Read Me First," which we place right on top inside
the box. One of our lead develpers calls this "the readme epic" -- the
daggone thing is generally eight pages long. That's just too much. And
there's no evidence that anyone reads it anyway.

We also add articles describing such things to our knowledge base so
customers can find out details about these changes. But the customer
won't go there until there's already been some problem with one of their

Have any of you successfully communicated this kind of information? I
welcome ideas and success stories. Please reply to me and I'll
summarize to the list.

Thank you,

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

Previous by Author: Fwd: WW hi tech writer
Next by Author: SUMMARY: Communicating obscure product changes
Previous by Thread: PageMaker plugin?
Next by Thread: Re: Communicating obscure product changes

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

Sponsored Ads