Re: Communicating obscure product changes

[Keith Arnett <keith_arnett -at- RESTON -dot- OMD -dot- STERLING -dot- COM>]

     Jim:

     From here, it looks like you are caught in a common tech writer bind:
     the development staff justifiably wants to document minor tweaks to
     the product, but unjustifiably asks you to put them in the user doc.

     My own experience is that this is mostly due to limited thinking; the
     user doc is the most convenient container, so the developer thinks,
     "OK, toss it in there."

     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.

     Regards,

     Keith Arnett
     Technical Writer
     Sterling Software, Inc./Operations Management Division
     Reston VA USA


______________________________ Reply Separator
_________________________________
Subject: Communicating obscure product changes
Author:  JGREY <JGREY -at- MADE2MANAGE -dot- COM> at INTERNET
Date:    4/6/98 8:56 AM


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.

<snip>

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