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.
- Anybody can ask a question
- Anybody can answer
- The best answers are voted up and rise to the top
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.
I can list out based on my experience. Release notes need to cover below items
These are couple of items I found useful for QA Team, Production Team and Product Mgmt team as well.
Hope it Helps..
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.
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:
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.