Release Notes Best Practices

Question

What are some tips for writing good release notes? Any best practices or examples? My audience is both my QA department and the executive team.

Answer 1

Since my company works with multiple clients and releases may or may not affect all of them based on custom features in their install we use Release notes to the development & project management teams to:

• Communicate which bugs were fixed
• Communicate the new features included with the release
• Communicate the release version
• Specify which client is most impacted by the release
• Communicate SVN revisions and merge targets

Our support project manager will then take those release notes and update our product updates page with details that have been "clientified" for public consumption.

Answer 2

We are using 2 different types of release notes, depending on whether it's a regular release of our software, or an intermediate one.

Normally the software I'm responsible for has one major release a year and it comes with full documentation (user manual, online help etc). For this release the release notes contains a section listing the new and modified features and the bug fixes. For the new and modified features there is also some kind of link to the documentation, e.g. "for additional information concerning this feature see chapter 3.2 of the user manual".

For intermediate releases, which are necessary due to bug fixes or features a customer needs so desperately that he cannot wait till the next major release, besides the list of new/modified features and bug fixes, there is also a description how to use the new or modified features from the users perspective. This information will be included into the documentation (user manual, release notes) of the next major release of the software. This is also true for bug fixes, which made it necessary to change the user interface or the way of handling the software.

Answer 3

I can list out based on my experience. Release notes need to cover below items

• Details of Release Feature - Whether this release is a feature additon / bug fix / Change Request
• Prerequisities to run the build - Any prerequisite that is required prior to build installation
• Environment for the build to be applied - You might have some scripts for DB, IIS, Biztalk ..It would be useful to callout the script target to install/run
• Duration of Script execution - If the build requires downtime, It would be useful to specify the installation time for critical steps. This would provide good insight on time to install and also estimate production downtime
• Log file path / Build Errors - Path to check for Errors / Troubleshooting (Call out if any known issues/ errors)

These are couple of items I found useful for QA Team, Production Team and Product Mgmt team as well.

Hope it Helps..

Answer 4

I distinguish between release notes and release contents. (The specific terms do not matter, and you may use different terms than I do).

The release notes is an externally-consumed document that helps users understand what is new in the release. It usually describes new features. It may or may not describe bug fixes, depending on the product, the type of customer, and how transparent the company wants to be. Some product have release notes; others do not.

The release contents is an internally-consumed document that fosters communication between teams on a project. It might start with a high-level description of the release's major themes, a list of features, and perhaps a list of significant fixed bugs.

To answer your question, you need to calibrate your release notes to the needs of your QA and executive teams. Their needs are probably different. Your executives may only want a high-level description of the project, whereas your QA team may care less about the high-level themes than in the actual features and significant fixed bugs. (These days I suspect companies rely more on bug tracking systems for bug statistics than in written documents.)

You did not mention your customer service team. Perhaps you do not have one, or perhaps your QA team is also responsible for customer service. Customer service will probably want both kinds of documents.