Brilliant strategies for release notes

[Anne Halseytechwriter <ach -at- TOMICHI -dot- STORTEK -dot- COM>]

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
            tried.

Luck!

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