Release notes are an essential part of software development. Whether your release is a bug fix or a major new version, inform the customers about what has changed. They expect clear details that tell them how to use new features and which bugs are (or are not) resolved.
So, how do you write good release notes?
Well, follow the checklist below – checklist for writing impeccable release notes. While it is not exhaustive, it should be a good starting point. Take a cue & change it to match your processes.
- Name of the product or service or component
- Version number/identifier
- Name of company that has released the change
- Release date
- Previous version number/identifier
- Compatibility with older versions
- Media in which the update is distributed and the available distribution modes
- Urgency of the update. Is this a security patch or a suite of new features?
- A link to the changelog.
Changes and Fixes
The bulk of the release notes should be a terse, clear list of the changes and bug fixes in this particular release.
- Split changes into “Fixed” and “Changed.” If there are no bug fixes, you can leave off the fixed heading or the other way round.
- Be mindful of the sections you are adding items to.
- Place fixes and changes in a clear order which makes sense, grouping changes to the same or similar features together.
- Explain each change & fix is clear, understandable.
- Add annotated screenshots, videos or gif images if that helps.
- Write the content of release notes such that customers can easily see how a change or fix benefits them, especially for non-critical releases.
- If you are using a template document from the last set of release notes, make sure nothing is held over. Avoid copy paste like manual errors.
Once you have the changes in order, check for consistency with prior release notes. This means:
- Checking that the tone and voice is similar. The easiest way to achieve this is to have the same team member write the release notes. A style sheet or template is a good idea.
- That the release notes are provided in the same format(s) as last time.
If your project has outside contributors, or even internal ones who are not on the core team, mention them in the release notes.
- Set up a kudos section
- And that everyone is credited correctly at appropriate places
Don’t add this section if you have no outside contributors or your release notes do not demand mention of internal team.
Especially for major releases, provide information to users on supported hardware and software.
- Share the minimum and recommended hardware requirements
- Mention the minimum and recommended operating system requirements
- Clearly state if you are deprecating support for an older version of the OS.
- Use a file format that can be accessed by all customers.
Provide the needed information for users to upgrade smoothly from previous versions, especially for major updates that need some additional efforts for upgrades.
- A full description of how to install the software. Assume users are starting from scratch & do not have any previous knowledge about this.
- Information on how to back up data and configuration from the previous release.
- Information on how to restore data if needed.
- Contact information, for if the installation does not go smoothly.
Again, this may not be needed for smaller patches where an in-app upgrade system is used to install the software.
Once all of these things are in, edit the release notes. Follow these steps:
- The original writer reads the release notes out loud (this helps spot typos).
- Somebody else on the team reads the release notes to make sure that they are consistent and refer to the right features.
- Ideally, somebody not on the team reads them to make sure they are clear to the user.
It’s not uncommon for release notes to ship with typos or errors in them. This can be very off-putting to customers, especially when the release notes are available on the web and being used as part of your marketing or a way to encourage people to pay for a new version.
Check all of these things before you send out the new version of your software and/or post release notes to your website. Good release notes are vital for a good user experience and help ensure that your users upgrade to the latest version.