Release notes are a vital component of any update of software and apps. They let the reader know what has happened since the last release, for example, what bugs have been fixed and if there have been any new features added. Release notes can be written for both internal and external audiences. This can affect the detail and contents that you put in your release notes. To help you to write better release notes for both internal and external audiences, we have compiled a list of five top tips:
- Keep your audience in mind
- Don’t be vague
- Organise your release notes into sections that contain bulleted lists
- Include links to supporting information
- Ensure there is continuity between release note editions
Keep your audience in mind
When writing release notes you should think about who you are writing the release notes for. Are the release notes aimed at an external or internal audience? There are times where the release notes that you are writing will work for both audiences and you will only need to write one set of release notes. However, you may find that you need to create two different sets of release notes for external and internal audiences. It’s important to keep the end reader in mind when writing your release notes because your intended audience will have an impact on the following factors:
- Detail: Be cognizant of the experience level of your audience and adjust the level of detail accordingly.
- Technical complexity: Adjust the level of complexity provided to the needs of the target audience.
- Tone: The tone of external and internal release notes can also differ because often, you may want to take a more friendly tone with your external audience whereas you may want to use a more business-appropriate tone with your internal release notes.
Don’t be vague
This is an important guideline when you are writing both internal and external release notes. It is critical that you are specific about the changes that have been made since the last release so that whoever is reading the release notes will know exactly what has changed. For example, if you have fixed three bugs and added two new features since the last release, you should clearly identify these in separate points. If you combine these into one sentence such as “bug fixes implemented and features added”, there is no way that the reader can know what has changed.
Organise your release notes into sections that contain bulleted lists
To make your release notes as user-friendly as possible, you should organise them into sections that contain bulleted lists, with one bullet per item. Use section names such as Bug Fixes, What’s New, Known Issues, and so on.
It is also important to maintain the same structure between release note versions. This makes it easier for users to find the information that they are looking for, as the structure is familiar to them.
Include links to supporting information
If the release includes updates to documentation such as user guides, installation guides, and so on, you should provide links to these in the release notes. Similarly, in external release notes, you should provide a link to customer support, so that customers can get any additional information that they require about the updates.
You can also use your release notes to accommodate documentation updates to describe features or information that is not yet in the product documentation. When the information is rolled into the core product documentation, it can be removed from the release notes.
Ensure there is continuity between release note editions
You should ensure that your release notes follow up on the information shared in previous versions. Users are looking at your release notes to see if there have been any updates to what was shared in previous iterations. For example, a known issue in one release may be a resolved issue in the next release, or a new issue may be discovered between releases.
To conclude, release notes are a critical component of any software update because they inform the reader about what has changed since the last release. Use our five top tips to help you to write better release notes for both internal and external audiences. How did we do? Let us know your thoughts and share your own top tips in the comments section below.
Images Used
- Image by NordWood Themes, licensed by Unsplash
