Need Release Notes Advice (fwd)

[Barbara Hallnan <barbara -at- EJV -dot- COM>]

Forwarded message:
>From barbara Wed Mar 20 12:19:09 1996
From: barbara (Barbara Hallnan)
Message-Id: <9603201717 -dot- AA11283 -at- nymailhost>
Subject: Need Release Notes Advice
To: techwr-l -at- listserv -dot- okstate -dot- edu
Date: Wed, 20 Mar 1996 12:17:49 -0500 (EST)
Cc: barbara (Barbara Hallnan), debby (Debby Paley)
X-Mailer: ELM [version 2.4 PL23]
Mime-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Content-Length: 2628


Release Note Writers:

In the release notes for our products, we have
a section called "Problems Fixed in this Release."
We have always written the entries in this section
as follows. First the problem is stated in past tense
(indicating that it's history). Then, if there is
a new behavior as a result of the fix, it is stated
in present tense. Or, if we think it might
not be clear exactly what the behavior should be now
that it's fixed, we state the current behaviour.
Then we cap it off with a
boring, repetitive "This problem has been fixed."
at the end of each entry, to reinforce for the
reader that yes, this problem has been fixed.

Here are a couple of examples, in case my description
doesn't say it all:

* The API was not accounting for puts to
Assumed.Scenario.Reinvest.xxx that were followed by puts
to Assumed.TradeDate. This problem has been fixed.
Puts to Assumed.Scenario.Reinvest.xxx
are now properly maintained. To revert to default values,
put a NULL value.

* Rate of return calculations for pools were incorrect.
Horizon cash flows were being calculated from SMMs and
projected coupons that started at horizon instead of
at Assumed.SettleDate.0. This problem has been fixed.
SMMs and projected coupons now start at Assumed.SettleDate.0.

* On Portfolio Holdings, when you used the Edit Column
Values box to change values quickly, values less than 1.0
required a leading zero. For example, ".5" was ignored
but "0.5" worked. This problem has been fixed.

Now that you have been snowed with financial speak,
let me get to the question. One of our managers
has requested that release note entries be stated as
positively as possible (a noble goal). One writer has
recast the problems fixed entries so that they read
something like this:

* Gov/Corp User Security no longer crashes when you
enter a maturity date prior to the current date.

or

* In Portfolio Holdings, when you use the Edit
Column Values button, unpriced securities are now
excluded from the aggregate calculations.

This method of phraseology is indeed more positive.
What bothers me about it is that the reader has to
reverse the logic to identify what the problem was.
In the second example, reversing the logic could
create confusion for the reader (i.e., I think it's
not clear what the impact of the problem was).

How do _you_ handle "Problems Fixed" phrasing in
your release notes?

Which approach do you think has more merit, and why?

Thanks in advance for all your thoughtful responses.

Barbara

barbara -at- ejv -dot- com
Barbara Hallnan
Tech Writer and Doc Manager
EJV Partners, a Division of GFIC
New York, NY