Re: Communicating obscure product changes

Subject: Re: Communicating obscure product changes
From: Keith Arnett <keith_arnett -at- RESTON -dot- OMD -dot- STERLING -dot- COM>
Date: Mon, 6 Apr 1998 11:23:28 -0500


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.


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

______________________________ Reply Separator
Subject: Communicating obscure product changes
Date: 4/6/98 8:56 AM


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.


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: Re[2]: Defining Readability Levels
Next by Author: Re: Ways to indicate spaces in command lines?
Previous by Thread: Re: Communicating obscure product changes
Next by Thread: Re: Communicating obscure product changes

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

Sponsored Ads