Brilliant strategies for release notes

Subject: Brilliant strategies for release notes
From: Anne Halseytechwriter <ach -at- TOMICHI -dot- STORTEK -dot- COM>
Date: Thu, 14 Jul 1994 08:54:40 -0600

Kelly Hoffman asks:

> 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?

The strategy that I found works the best is a multi-parter:

1. About six months before a software release/upgrade,
send out a product information bulletin identifying
those subsets of functions that will change in
any significant way and provide a 'heads-up' for
announcing new functionality.

This gives folk who may be building applications on
top of your stuff warning that changes, they be
a coming.

2. Provide a document *with the release* which provides
details concerning the enhancements. (This can be
called "Update Notice" or "Release Notes" or some
such thing.) Ideally, the notification of a specific
change should contain a reference to the doc/section/page
where the change is documented.

For example, assume you have changed the default
location of the home directory structure from
'home.loc' to 'castle.loc'. This could be reflected
in your release notes by:

"The default home directory is now "castle.loc";
see "Setting the Home Directory" on page 2-2
of the Installation Guide for details concerning
this change ..."

or some such.

3. If you are able, put some sort of statement up front
in the install script which reminds customers to review
the release notes doc. Make them acknowledge with a
keystroke or something before the install can continue.

This ensures that they have to at least acknowledge that
you're trying to help them. If they still don't read the
doc, you at least can sleep well at night knowing that you


anne halsey
sr tech writer, storagetek
anne_halsey -at- stortek -dot- com

Previous by Author: Re: Finding out if anyone reads your stuff
Next by Author: Re: Software documentation--when to begin?
Previous by Thread: Re: Tech Writer Positions
Next by Thread: okay, back to work

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

Sponsored Ads