Importance of Release Notes

All software development teams use release notes. Whether they know it or not, is a different question altogether.

For example, 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, new features & bug fixes? Answer would be an emphatic YES.

Teams might disseminate above information through different channels. Such as email, blog posts, in-app notifications etc. But their content is definitely worthy of being called ‘release notes’.

Why publish Release Notes?

Software development is becoming more & more fast paced. Adoption of scrum & kanban processes is the top priority for teams. Domination of SaaS model tends to give more power into 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 publishing release notes makes sense. 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.
  • Technical details in release notes 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, number of bugs fixed, estimated time vs actual time, new bugs introduced  etc.
    • These stats can play crucial part in optimising the entire release management process.
  • As maturity of the software increases, release notes become a reference point of documentation.

What to include in Release Notes?

Most common question when it comes to writing release notes is, what should be included & what shouldn’t? Well, there is no one size fits all answer to this one. It certainly depends on who the audience is. Are they technically conversant? How deeply they engage with your software? What are their interests? 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. Involving marketing team, customer support team is a wise move.

Some of the common items to include 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 features
    • 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

Material to get you started on Release Notes

There is plenty of material available around writing release notes. But the final call needs to be taken considering your target audience. Below is a list of change logs of some famous softwares/tools. Feel free to take a cue from them.

References

Take a look at our app for Jira that can automatically generate release notes in various formats. Automated release notes for Jira. This app is available for Jira cloud, server as well as data center.

Anand is on a mission to help organisations build winning teams.
Share this article