Release notes mistakes to avoid
The language barrier between developers and customers of their products is vast enough to render any release notes useless, if they weren't altered first. Typically, the process falls on the product manager who translates the technical changes made and transfers that understanding into release notes.
Not talking to the users
Here, the product managers can take help of sales and marketing teams to craft their latest release messages better – a normal ‘Feature [X] is now available’ may not be understood by the users, but ‘You can now do [X]’ gives a very clear direction.
Generic release notes cause more harm than good, but large companies might have no recourse – apart from creating release notes, they also have to ensure translations into multiple languages and ensure that the meaning is not lost. This is more likely to happen in case of big releases, where the number of updates and fixes might be significant. Picking and choosing updates to put in the notes template can result in information overload.
Not keeping short
Treating Release notes as a laundry list of changes is another issue that causes users to turn away from them. Just listing the updates and changes carried out without realising what users want to know might result in a comprehensive release document, but it will not be of any use to anyone.
Examples of great release notes
Great release notes are short and concise. They can be thought of as the metadata of the project or product: They default to a list of new features present in a release, mention bug reports if any, and then move on to describe changes that are most important and impactful in that release. Making the explanation for the change concise enough to fit in a bullet point or short paragraph, holds the attention of the user and the likelihood of the feature being used increases.
Great release notes are accessible
No matter how well-written the release note is, if it isn’t accessible to users easily, it will not be read. Users are accustomed to working with the product or solution in a certain way, and changing it without clearly elaborating on it can make them look elsewhere for a solution. Easy to find release notes are accessed by existing customers, new users, and prospects who are looking at a possible solution.
Great release notes are organized
Release notes don’t have a defined structure overall, but they need to have one within an organization. Any given release could have bug fixes, new feature introductions, add-ons and so much more. Having a loosely defined structure, therefore, allows users to quickly scan and identify the information they’re looking for. Someone who has been plagued by a unique bug might directly jump to the bug fixes section, while a more casual user may be interested in the new filters added.
Release Note Software
Generating release notes after every update is a monotonous activity: the different kinds of formats, ensuring consistency with the previous release notes, highlighting and communicating changes to stakeholders – the effort is massive, and instead of writing them, your team could be doing something else that makes more business sense.
Quick formats, quicker sharing
ARN creates release notes based on customisable templates for email, PDF, Confluence page, Markdown, JSON & HTML formats. The layouts of the reports can be modified, and JQL can be used to choose Jira issues to be included along with the information that needs to be shown.
In order to trigger generation of release notes, rules can be set – so that relevant people to groups get the information they need, in the way they can quickly digest. Ve it an email to the higher ups, a pdf for client review, or an email chain among colleagues – ARN can generate reports based on any rule that is set. Even webhooks are available for integrating with other tools.
Additional Release Note resources
Release notes is an untapped exercise for customer & stakeholder communication. With targeted & useful content you can actually increase the engagement with your product & processes. Automated release notes for Jira takes away the tedious, manual stuff and brings in efficiency with the power of automation.
FAQ on Release Notes template
Why do we need release notes?
Release notes are necessary for users to understand the changes and developments made in the product or solution. They also provide a roadmap and history of the product, and chronicle the changes in one place.
How do I make a release note?
While organizations can structure product release notes as they want, there are some common elements that need to be present.
- Header that includes the name of the product, release number, and date of release
- Overview section gives a brief description of the contents of release notes.
- Issue section lists the bugs/issues addressed, and provides a short description – and steps to reproduce are described in case of a bug.
- Resolution section mentions the changes made to address the bugs, issues or feature requests.
- Impact section defines any actions that are needed to support the release, by users and/or confluence administrators.
Other than these, writing a release note should be a concise, to the point affair – users skim release notes.
How do I create a release note in Jira?
The bare bones reporting feature of Jira can be used to generate product release notes, and here are the steps:
- Pick Projects from navigation bar
- Select your project (either from the list, or navigate to the project from View all projects)
- Select Versions (Releases in Jira) in the project sidebar
- Select the Version (or release) for which release notes are to be generated
- Select Release Notes and click the 'Configure Release Notes' link
- Pick the right version from 'Please select version' drop-down
- Select the format in which release notes are required from the 'Please select style' drop-down
- Click the 'Create' button to generate notes based on a specific template in a specific format.
The display results can be copied and pasted in another document, or can be exported into the version desired.
What is the difference between release and version?
Before release and version, we need to understand what build is – it is an executable or a library created by compiling source code. As new features get added, the older builds (or executables) no longer work – and a new release needs to be created for the general public to use.
This release is a version that was deemed acceptable to be used by a certain set of customers. There are plenty of other releases in the middle, where changes either cause undesired results or fail to work altogether.
Build number is the number of times the main program or library has been compiled: That’s why it makes sense to only release builds with meaningful changes. Version 3.1.4 means it's the third edition with at least 1 major difference from 3.0, and 4 minor change events (bug fixes and/or updates).
How do I make release notes automatically?
Many app stores make release notes a central part of software updates, but few companies actually take the time to write and organise them for off-platform applications. The most accessible way would be to create documents with macro settings feature on Microsoft Word, but the complexity might be high. Release notes should be easily accessible, well-organized and written for humans, showcasing the features and bug fixes associated with each release cycle.
Automated Release Notes for Jira – Source: Automated Release Notes
Automated Release Notes is a Jira add-on that automates the generation of release notes & communication of those release notes to customers and stakeholders. By pulling from Jira issues and custom fields, ARN makes it easy to generate customisable release notes in a variety of formats. Some of the formats include email, PDF, Confluence, JSON, HTML and more.
ARN also has integrations for in-app notifications (pictured above) and can be triggered from your continuous integration system via a webhook. You can configure different versions of the same release notes to be sent to stakeholders prior to a release and customers after a release to make sure everyone is on the same page at all times.