Technical Writing
How to Write Release Notes: Tutorial & Template
Feb
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.
Download – Release Notes template with sample text.
Introduce the release notes with text such as the following:
These release notes provide information about the documentation for <your product> <version number>.
Download: Technical Writing Templates
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.
Download – Release Notes template with sample text.
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>
Download – Release Notes template with sample text.
