Introduction
Release notes are an important part of the product development cycle, release notes are valuable because they facilitate communication, provide transparency, aid in troubleshooting, and contribute to the overall understanding and improvement of a software product. They play a crucial role in ensuring that both users and developers are on the same page regarding software changes and updates. For extensive elaboration see appendix I.
Audience
Release notes will be published on the https://www.cm.com/release-notes/ website for external, as well as internal stakeholders. Within these groups of stakeholders, product users are the main readers of interest. Given this audience, Writers of the release notes should be mindful of the content they communicate.
Location
Release notes published on the product specific sub-pages of: https://www.cm.com/release-notes/
Frequency
As releases are pushed to production at an ever increasing rate, and stakeholders may be dependent on it's communication, the frequency with which release notes are published should preferably be performed as close to releases to production (Before or closely after) as possible. In this, it is the responsibility of the product teams to ensure that release notes get published as frequently and constantly as their proceses allow them to.
Content
Release note publications contain information regarding features, (Technical) improvement and bug fixes. In this, Feature, improvements and bug fixes are described in such a way that their value is clear and understandable for their intended stakeholders.
Best practices to write good Release Notes
- Give a clear, descriptive title. Someone that knows what we are working on should understand what it is.
- In the title start with one of the three words:
- Feature release - for things that are new
- Improved - for things that we’ve made better than before (e.g., faster, cheaper, easier)
- Bug Fix - for things that were broken, or not working as expected
- In the description clearly describe how this benefits our customers or colleagues.
- Put on your marketing hat, instead of engineering hat; write the text as an appealing feature.
- Ask yourself why a few times. 5 times should be usually enough to get to the core of the actual value that you deliver.
- If you talk about an app: link to that app. (Highlight text and press CTRL + K to create a hyperlink)
- Did you know that you can add pictures into the details? Remember that a picture says more than 1000 words.
- "BETA" In order to improve the documentation process of new features or functionality, tooling by Scribehow.com can be used to visually and intuitively describe new features to stakeholders. A short Scribehow.com guide: Example. Scribehows can be added to the release notes as an iframe.
Template
To provide a consistent release note experience to all stakeholders and improve the efficiency of the creation process, a mandatory template should be used by all product teams to create their release note publications. The format is highlighted in the following card: How to: Release notes template
Appendix I:
Communication: Release notes serve as a means of communication between the software provider and its users. They inform users about what changes they can expect to see in the updated software, helping to manage expectations and reduce confusion.
Transparency: They provide transparency into the development process by detailing what issues or bugs were addressed, what new features were added, and what improvements were made. This transparency helps users understand the ongoing commitment to enhancing the product.
Documentation: Release notes document the history of a software product's development. This can be useful for troubleshooting, as users and support teams can refer back to release notes to understand when specific changes or issues were introduced or resolved.
User Education: Release notes can help users understand how to use new features or take advantage of improvements. They may include instructions or links to documentation that explain the changes in more detail.
Feedback and Bug Reporting: Users who encounter issues with the software can refer to release notes to see if their problem has been addressed in the latest update. If not, they can report it, helping the software provider to further improve the product.
Security Updates: Release notes may include information about security patches or fixes. Users can prioritise updating their software when security vulnerabilities are addressed.