When it comes to making a good release note, there are some definite Do’s and Don’ts. This includes:
DO:
- Creating accurate, precise, and concise notes
- Positioning note’s from the user’s perspective
- Providing context so that the release note is understandable
- Explaining if there are actions the user needs to take
- Using simple wording
DON’T
- Simply mentioning an issue has been “fixed”
- Writing in an overly formal/impersonal manner
- Using language full of jargon or stylized language
- Providing too much technical detail or complexity
And, while every company is different, and each company will have its own layout and priorities when it comes to notes, there are definite ways NOT to present release notes to your user base. We try to outline those here, so you can avoid these typical mistakes and build a release note template that will ensure the success of your communications.
Example 1: Medium
While we’re big fans of the platform, the release notes of Medium can leave a lot to be desired. Sometimes they are vague (like in update 3.77), and sometimes they are repetitive (like in 3.79-3.82). There are opportunities to link to more information or to take screen grabs and show a user how to access the latest feature. However, they seem to take a “less is less” approach to informing their users of the latest.
Tumblr.
When it comes to creating release notes, it’s essential to stay consistent. Tumblr, for example, does an excellent job of keeping release notes simple. However, they seem to have trouble with organizing news in their subgroups sometimes. Case in point:
While on May 11th, they have an “Ongoing” issue section that lays out some errors users are experiencing (that they’re working on), on May 14th, the writers group an “Ongoing” issue under “Fixes.”
If your company intends to have various sub-sections within release notes, keeping the organization consistent will help direct users to pertinent information and keep them properly informed.
The worst thing about sending out a release note is having nothing to say. Linkedin seems to have nailed the art of never giving any real information about their app via their AppStore updates, which are, more often than not, simply a repetitive placeholder. Take, for example, these Linkedin updates from the summer of 2020:
And this Linkedin update from May 18, 2021:
Altium
Altium’s release notes provide more questions than answers. While the Release Notes for Altium Designer explain the issues at hand, they certainly don’t showcase with clear certainty that the issues are fixed. Instead, their release notes read like a list of problems with the product, with very little insight into actual solutions. Case in point:
By providing more context, or links to more information, the company could help a user better understand just how the changes highlighted affect them and/or if there is anything they need to do to adjust for the changes.
Our Takeaways
When it comes to writing release notes, it’s essential to avoid being cryptic or to share information that doesn’t add to a user’s better understanding of the product. If your release notes aren’t additive or informative, it’s likely unnecessary to even, well, release them. Being concise is important, but not at the risk of being uninformative. Remember, if you are trying to keep things short and sweet, you can always link out to further details and give the user the option of learning more…or not.
Our biggest takeaway after exploring what “not” to do, is to avoid looking lazy. That includes using canned language (clearly cut and pasted in from other release notes) or simply saying something to the effect of “a bug was fixed”. Remember: release notes are an opportunity to communicate with your audience. Coming across as lazy or disinteresting in your product may only serve to hurt your brand.
Have questions about Jira and Jira-focused add-ons? We’re here to help. Check out our range of apps designed to help you work smarter and faster.
Want more Bitband insights? Check out:
