Re: Communicating obscure product changes

[Dick Margulis <ampersandvirgule -at- WORLDNET -dot- ATT -dot- NET>]

Jim,

A couple of approaches (use both if you can):

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.

Hope this helps,

Dick



JGREY wrote:
>
> Techwhirlers,
>
> I'm struggling to solve a niggling issue.  I hope you can offer
> suggestions.
>
> 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
> this.
>
> 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
> customizations.
>
> 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
>
> jim grey \ Documentation Manager
> Made2Manage Systems, Inc. \ jgrey -at- made2manage -dot- com
>