Release notes?

[nancy ott <ott -at- ANSOFT -dot- COM>]

Kelly Hoffman <kelly -at- NASHUA -dot- HP -dot- COM> writes:

> How do you folks, particularly those of you who write software docs,
> handle release notes for a product?  do you just produce a laundry
> list of items that have changed?

> I'm interested in any alternative strategies that have worked for
> you and your readers.

We do two types of release notes here:

- An "Exception List", which documents the bugs and weird little
hangups that still remain in the software after the QA cycle has been
completed.  This is prepared by the product engineers, though
occasionally Documentation gets involved to flesh this out into a more
formal document.

This type of release notes is usually distributed as a "readme" file,
or sometimes as loose pages inserted into the documentation.

- A set of formal release notes for updates that don't involve a huge
amount of interface changes -- for instance, if a new release adds a
few commands but doesn't change the program flow.  These release notes
function as addenda to the existing manuals.  In a sense, they are an
intelligent laundry list.  We list the new features or changes in old
features, then fully document them.  When doing so, we try to present
enough related information that the users don't have to keep flipping
back and forth between the release notes and the original docs.  We
also update the index to include the material in the release notes.

This type of release notes is generally placed in a separate tab
section at the front of the binder containing the product's user's
reference manual, or in a separate spiral guide when the binder is too
small to fit the release note pages.

- nancy

--
-----------------------------------------------------------------------
nancy ott      | I would rather die for virginity than for petroleum.
Ansoft Corp.   | It's more literary, somehow.
Pittsburgh, PA |
ott -at- ansoft -dot- com |                - Kurt Vonnegut