Why automate release notes?

Tips & Tricks

Written by:

Reading Time: 4 minutes

Yes, automation is money thrown down the river for the sake of automation. But that doesn’t mean that all automation opportunities are the same. Manufacturers have gotten wise to the act ages ago, but the giants leading every industry have some legacy software they need to move on from (and believe they can’t). One of the main reasons is a lack of expertise in the old tools used and a lack of documentation following it closely. 

Sometimes, the organizations facing issues from lack of documentation and organizations not willing to invest in better documentation end up being the same, for vastly different reasons. Release notes explain what changes were made and why, what bugs were fixed (and how), and what features and enhancements were added. These details must be presented differently to the testing team, support, sales, leaders, customers, and other stakeholders. Usually, internal notes contain technical information about changes made, and external notes for clients and customers summarize those changes. 

Why release notes, and how to write one

Release notes are a pivotal piece of project documentation that don’t often get the importance they deserve. They establish expectations and increase the efficiency of the project. A release note meant for the testing team (for when a slew of new features get introduced or a high number of bugs are solved in the sprint) would include a list of ‘how-to’s and known issues so that the team’s efforts are spent on relevant aspects of the product. A template can be a hassle-free method to ensure release notes contain all necessary details, and automating them can provide further personalization. Product managers are responsible for creating release notes, and they usually start with the following sections:

  • A Build Identifier to keep track of the changes that occurred in the current release of the product, with the exact release name (code names are welcome, too).
  • Install and update instructions if required. End users – from the testing team to the customers (or their employees) – need to know if they have to take some action to get the update working. Even if no customer/end-user involvement is necessary, highlighting that a change has been made is essential in some cases to assure them.
  • Testing team pointers on the changes made and possible implications on other features – so that they can execute all possible scenarios. These also let them know what areas will not be affected so that they can exclude regions that would otherwise be tested.
  • Details on new functionalities include information on features that are added in the current release. This section can look different for different target audiences – end users can see screenshots on how to use features (if required), while leaders would get only the highlights (improve app boot time by 30%, for example).
  • Sunset lists provide details about the features or functionalities taken out in the current release. This section can also be seen as an informal ideas pool because the ideas were unviable a few years ago. After all, hardware limitations can be tried if they align with the business goals. Forms an essential part of ‘where not to go for future developers, and 
  • Implementation notes explain features that are implemented differently from the requirements. Usually, these describe tailored (or premium) features and can include screenshots if necessary.
  • Fix lists discuss errors or bugs fixed in the previous sprint and implemented in the current release. This section can also contain ticket numbers in the internal version so that future similar errors can be resolved faster.
  • To-do lists include features that are not completely implemented yet, and usually form a part of testing team versions of release notes. The testers on the project can exclude these instances. They let testers know about the existing issues and workarounds until a permanent fix is made. 

‘Release’ notes from the manual creation.

As usual, the product manager starts the custom process and prepares for its creation to distribution. The process takes days, if not weeks, of a product manager’s time. It is not enough to generate well-written release notes; they must be shared in multiple formats.

Automating the process solves the issue once and for all. Release notes can be created in multiple formats – with predefined templates for email, PDF, Confluence, Markdown, and JSON & HTML formats with ARN (automated Release Notes). The Jira-native app modifies layouts to match the needs of its users and uses JQL to include Jira issues with relevant information attached. Dedicated release pages and in-app widgets in ARN allow customers to subscribe and provide feedback. Different rules can be set up to generate release notes based on needs and are triggered via version release (or as scheduled, or manually). Webhooks for integrating with other tools are available too. The application uses Jira’s native ticketing platform to create and maintain a log of issues, which are then classified accordingly. Relevant details are pulled from these tickets, and the information is seamlessly combined with the selected template to generate release notes in the format required. 

Conclusion

Good release notes can grease the wheels of release cycles very well and make them highly efficient. But they are usually treated as a chore to be done with, at best a nuisance like a captcha. They’re written poorly to avoid any mistakes; a mistake technical manuals have been committing since the sun’s dawn. By removing the strenuous part of generating notes, organizations can empower their product managers to craft them in a readable manner (instead of preparing them all with the exact words and different formats. Release notes can play a vital role in the overall product experience because they provide a valuable opportunity to communicate with customers and your broader market. When done well, they have the potential to nurture engagement and increase customer loyalty. Their absence leads to repetitive work like issue duplication or increased project hours. But as the benefits are enormous, organizations should seriously consider automation to remove repetition and effort duplication. With the significant downsides taken care of, the entire team (including the product manager!) can focus on perfecting the release.