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.


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.

| improve this answer | |
  • We really never did release notes until now. The business had no requirement for one, other than a complaint about not knowing what just went live. I'm simply including a list of features that they've requested which were implemented in the current release, along with the descriptions from the requirements documents. They really just want visibility into what changed. – Mark Richman Mar 18 '12 at 21:19

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

| improve this answer | |

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.

| improve this answer | |

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.

| improve this answer | |

This investigation/project ARENA: An Approach for the Automated Generation of Release Notes is very interesting and trying to answer the question by scientific-engineering argumentation, plus provides an online tool at https://seers.utdallas.edu/ARENA/

Additionally, because the study is always limited, I would pick some random high-light release notes (see list) and than specify your notes.

My background is over a decade in R&D so I have seen a lot. From another point of view, release notes seem not to have major project impact, i.e. if their quality varies the risk is still low. Stakeholders such as customer or PM of course will require them. Nor have I seen release notes as major documents used or relied upon in QA or specification activities. Think assessments. I would consider them part of Configuration Management.

| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.