All software development teams use product release notes. Whether they know it or not, is a different question altogether. These notes help users understand the advantages of a new feature, help marketing teams to orient their sales template for the product accordingly and provide a way to plan the future work for dev and QA teams.
What are software release notes?
When the development team makes some changes to the application and hands it over to QA. Do they inform the QA team, what has changed? what needs testing? what are the known issues?
Now extend the same analogy to production releases. Are the customers informed about enhancements? Are users informed of a new feature (or features) & bug fixes? The answer would be an emphatic YES.
Teams might disseminate the above information through different channels such as email, blog posts, in-app notifications, etc. But their content is worthy of being called ‘product release notes’.
How do You Write a Software Release Note?
Software development is becoming more & more fast-paced. Adoption of Scrum & Kanban processes is the top priority for teams. Domination of the SaaS model tends to give more power to the hands of devs. DevOps tends to push the envelope by increasing release frequency.
Bottom line is – there are more releases than ever & more frequent. Here’s a quick list of why it makes sense to write release notes. The first couple of points may seem obvious. But after that the list becomes intriguing –
- Keeping all the stakeholders informed about changes in the product. Stakeholders include
- Internal – devs, QAs, release managers, support agents, executives, business team/s.
- External – customers, vendors, affiliate partners – anybody who is an end-user.
- Technical details in release documents help keep track of metrics. Such as build failures, test automation results, build time, environment responsiveness, etc.
- Internal facing: can also keep track of statistics such as story points released, the number of bugs fixed, estimated time vs actual time, new bugs introduced, etc.
- These stats can play a crucial part in optimizing the entire release management process.
- As the maturity of the software increases, release notes become a reference point of documentation.
What should go in Release Notes?
The most common question when it comes to writing release communication is, what should be included & what shouldn’t? Well, there is no one size fits all answer to this one. It certainly depends on the user base: Are they technically conversant? How many users deeply engage with your software? Do you know the interests of your users? and so on. One can use different tones & depth of information based on these details. Whether your software is on-premise, works in the cloud, or is only a desktop app will also wield influence.
Coming up with release communications is thus not just a technical writer’s job. It should ideally involve the marketing team and customer support (for personalizing offerings and solutions based on the needs of the customers).
Some of the common items in great release notes are listed below. Do note that this is not an exhaustive list & not all of these will be applicable in your case –
- Build & version identifiers
- Installation & update instructions (if applicable)
- Advice for QA team (if internal)
- Featured items (for external facing)
- New feature section
- Number of votes
- Improvements
- Impacted features
- Bug fixes
- Priority & severity
- Known issues
- Product screenshots
- Documentation links
- Tentative next release date
- Brief details around what to expect in the next release
Who prepares the release notes?
There isn’t a clear answer to this – as large organizations usually have entire teams dedicated to release notes. But in medium to small organizations, the responsibility falls on the product manager.
In order to prepare release notes, though, the person in charge should have enough technical knowledge to understand the issues addressed, and then present it in an easily understandable manner.
What are the 5 major points which must be part of release notes template?
Release notes differ from organization to organization, but the common practice is to include relevant information in a structured manner. The major sections that are usually a part of every release notes are:
Header – Product name, release number, and date of release go into the header.
Overview – A summary of features addressed or introduced, with an emphasis on new features.
Issue Summary – List of bugs/issues resolved, with a short description of what was done. Brief descriptions on how to reproduce the bugs can also be included.
Resolution – List of changes or enhancements made to address the issues or requests.
Impacts – the changes necessary in configuration, prerequisites, hardware, or some other field can be listed here. These can serve as action items for stakeholders that support the release in question.
What’s new on Release Notes
There is plenty of material available around writing release logs. But the final call needs to be taken considering your target audience. Below is a list of changelogs of some famous software/tools. Feel free to take cues from them.
References
Take a look at our app for Jira that can automatically generate release documents in various formats: Automated release notes for Jira. This app is available for Jira cloud, server as well as data center.
