Release notes are an important part of a product
release, they contain specific information about
a particular product version.
Release notes can make the difference between a simple,
straight forward install or a disastrous upgrade
that shreds your data and takes days to recover from.
They should be able to provide the reader with the
information they need to satisfy their questions.
The main question always being -
why do I need to upgrade ?
A good set of release notes will give the reader
confidence in the company, product and version as
their software engineering process can be reflected
by their release notes.
While a bad set of release notes will tell the
reader nothing, except that by reading between
the lines (or lack thereof) that the software engineering
process is not up to scratch.
A release notes template which can be used as a basis
for your product release notes will typically contain
the following sections.
The advantage of using a template is that your
release notes will all be in the same format
which will ensure that all the necessary
information is included.
Each item may be included or omitted depending
the type of product, project, application or release.
The following information describes the
sections in more detail.
System requirements
The new release may require additional hardware
and resources or perhaps new versions of required
(or dependent) software that must be installed first.
This section can include supported operating
systems or hardware platforms.
Installation
This section should contain notes on installing
the product.
It might simply point to a separate installation
document if it is a lengthy process.
Upgrading
Special notes on upgrading from a previous version
should be included in a separate section.
These may also need to include notes on upgrading
an installation that is several versions old.
If the instructions are detailed and lengthy then
this section might just point to a separate document.
Also special attention should be paid to data changes
(such as database tables) or perhaps the File
and Directory structure as these are things which
may affect some advanced installations, for
example, you might need to get a database
administrator to allocate additional table space,
etc.
Whats New
This section should give an overview of the
new features or enhancements that are included
in this release along with the main reason or
focus of the release
(there should always be a reason for a release !)
This section (along with the Changes in this release
section) should enable the reader to make the
decision on whether this upgrade is relevant
and necessary for them.
This is important as it can save the reader
a lot of time.
Changes in this release
Information about the changes and corrections
to problems in previous releases can be placed
in this section.
It can include the bugs that have been corrected
and perhaps how they have been corrected.
The level of detail and technical content can
vary depending on what the product is, for
example, a complicated middleware application
that has multiple integration points would
need a detailed description of each bug fixed
including the Bug Number, Symptom,
Cause and Correction detail items
whereas a simple application such as an editor
may list a summary of each correction.
Outstanding issues
This section usually includes minor problems that
have been found while testing and creating the
release.
Known limitations
This section includes limitations of the product,
for example, problems which occur on a specific
platform.
Contact information
This section is good for directing specific release
oriented questions to desired area.
Supply an email address of the person or organization
responsible for creating the release.
If there is a product web site which contains
the latest news and documentation then supply a link
to it here so that people can look to find late
breaking news and information.
Automatically generating release notes can be a
way of saving time and resources.
The information contained in release notes is
fairly static except for the Whats new
and Changes in this release sections.
However, information for these sections is usually
contained in the bug tracking system that
your company uses.
If you have entered all the information about
each bug, and you have a list of the bugs
fixed in the release you are making, then it
should be easy to generate the information.
One way of doing this is by using the reporting
features of your bug tracking system to generate
a report and then transcribing the information into
the notes.
Some bug tracking systems allow you to create
and manipulate the bug list first and then
generate the release notes using a user
supplied template,
Ozibug
is one such system.
Creating good release notes is a fundamental
part of the Software Engineering lifecycle
process.
Spending the time and effort to create the
release notes during the test and quality
assurance process will return a higher
quality product while also reducing support
costs.
