How to write release notes and Jira release notes checklist
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 great release notes?
Well, follow the checklist below – checklist for writing great release notes. While it is not exhaustive, it should be a good starting point (more so if you are planning a new release!). Follow agile release planning if you want to focus on incremental releases of the product. Take a cue & change it to match your best practices.
What should be included in a release note?
- Name of the product or service or component
- Version number/identifier
- Name of the 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
- The 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 product 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 & the 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.
Consistency
Once you have the changes in order, check for consistency with prior release notes. This means:
- Checking that the tone and voice are 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.
Kudos
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. Ensure your release notes do not demand mention of the internal team.
Support
Especially for major releases, provide information to end-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.
Installation/Upgrade Guide
Provide the needed information for users to upgrade smoothly from previous versions, especially for major updates that need some additional efforts for upgrades.
Include:
- 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.
Editing
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 free of technical jargon so that users can understand the contents easily.
What is the point of release notes?
Catering to a multitude of users who have different expectations from the software they use, is a major reason to maintain release notes. Having a dedicated space for release notes online also helps users see the progress and the commitment of the team towards the product.
What is the best way to write software release notes?
There is no one best way to write notes – as the needs of different stakeholders need to be addressed differently. Using a plugin like Automated Release Notes can reduce the amount of work on the managers, who can then focus on getting the release process right. Thus following release notes best practices can help you get started with ease.
Who is responsible for product release notes?
While the product managers ensure the issuance of release notes in small and medium organizations, large ones can have entire teams dedicated to the process. But the major point to be considered here is that the team member(s) charged with creating release notes should have enough technical know-how to understand the issues that are addressed in the release, and put it in a way that is understandable by the average user of the product. They can leverage release management tools to manage the process of software release and delivery.
How to communicate product changes to your users
Release notes are a succinct way of ensuring users know what has changed in the product. They also ensure new users see the most recent features and updates first. The brevity of release notes can cater to a wide range of users, who then can pursue the sections with information that pertains to their usage.
Final check
It’s not uncommon for release notes to ship with typos or errors in them. This can be very off-putting to customers (who might highlight it on social media!), 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/app store. Good release notes are vital for a good user experience and help ensure that your users upgrade to the latest version.
