How to Write Release Notes: Faster, Stronger, Better

release-notes-how-to-write

So, you want to write release notes but don’t know where to start?

Well pull you a chair and let me give you the lowdown.

Here’s what you need to know, grasshopper.

They say ‘Keep it Simple’ and its true.

Introduce the release notes with text such as the following:

These release notes provide information about the documentation for <your product> <version number>.

release-notes-template

You can download release notes templates here.

About This Release

Next, describe what’s included in the release, especially if it’s quite detailed, for example:

This release is a full version of the <your product> <version number>. It can coexist on the same computer with earlier point releases of the product starting from Version X.x.x.

Identify where you can find the software to download.

Where to find the software to download

To download the software for <your product> <version number>, go to <URL>.

For details about supported hardware and software, see the system requirements.

After you install the software for this release, go to <URL>to download and install any Interim Fix releases. For details about interim fixes, go to the Support website.

For an overview of new features in this release, see the What’s New section.

For answers to Frequently Asked Questions and workarounds for known problems, view the release notes on the Support website.

Prerequisites

Identify any software, drivers, or patches that need to be installed prior to using the application.

What’s New

Next, describe the new features available in this release. These are not enhancements but larger pieces of functionality, for example, a new module, service, window, or other piece of functionality. Enhancements tend to be more related to improvements to existing functionality. For a large release, you might want to keep these separate.

For example:

The following new features are available in this release:

Access management

This release contains an optional feature for managing access to the software. Access management helps you to maintain compliance with the terms of your software agreement. For more information, see the Access Management Guide.

ArcGIS 10.1 support

Geographic Information System Interfaces now support ArcGIS 10.1.

Note: <your product> X.x does not support Microsoft SQL Server 2012 databases.

Compatible companion products

If appropriate, include this section:

You may have purchased one or more <your product> companion products. The following versions of companion products also work with <your product> <version number>: <product x> and <product y>.

Configuration options for <your product>

You can run <your product> <version number> on a system configured in a number of ways. Regardless of how the system is configured, it will contain these elements:

<product>

<product>

<product>

System requirements

Next, identify the mandatory or minimum system requirements:

For information about hardware and software compatibility, see the system requirements document at <URL>

Documentation and Examples

Next, identify any new documentation and code examples

The <your product> documentation is updated for this release and is automatically installed with the product.

Known Issues

Next, identify the features that are now available. Number the features so you can track them.

The following issues have now been resolved.

# Issue Solution

1

2

3

4

5

Enhancements

Next, identify the enhancements that are now available. Number the enhancements so you can track them.

The following enhancements are now available:

# Enhancement

1

2

3

4

5

Deprecated features

Next, identify deprecated features, for example:

IBM defines deprecated as ‘Pertaining to an entity, such as a programming element or feature, that is supported but no longer recommended and that might become obsolete.’ See the IBM Terminology URL: http://w3-01.ibm.com/standards/terminology/cgi-bin/lookup.pl?user_group=corporate

The following features are being marked as deprecated in this release.

Invoke function

Any policy that uses Invoke function can use the InvokeDL function instead. The WSDL file must be recompiled and the policy must be rewritten to accommodate the changes.

Removed features

Next, identify removed features, for example:

The following features were removed from this release:

The graphic view feature in the policy editor.

Integrating with SQL Server.

The following features were marked as deprecated in X.x.x and have been removed from this release.

The following documentation changes apply to this release:

The Troubleshooting Guide has been replaced with a Troubleshooting wiki page available from the following <URL>

PS – Be good to yourself and grab this Release Notes template.

Have you got these templates?