Release notes are often an afterthought during the development cycle. But with a little effort, they can become a valuable way to increase customer loyalty and retention.
If you’re already writing release notes on a regular basis, you should check to make sure you’re not alienating readers with four common release notes mistakes—and if you are, we’ll show you how to fix them.
Let’s take a closer look at four common reasons that nobody is reading your release notes and changes that can make them more impactful.
Are your release notes alienating users? Here are four tell-tale signs that you need to change them! Click To TweetRelease Notes Mistake #1 – They’re Too Technical
It’s no secret that there’s a language barrier between developers and the rest of us. If you leave release notes to the development team, you may find that you need a Ph.D. in computer science to understand them.
Product managers are typically better suited to translate developer-facing user stories into informative and easy to understand release notes.
The best way to write approachable release notes is to follow a well-defined set of templates that speak to the user. For example, when releasing a new feature, instead of saying, “we built a new feature that [does something]”, it may be better to say, “you can now [do something]”.
Common examples of these templates include:
- [This] is now [that].
- You can now do [this] instead of [that].
- [This] no longer does [that] when [doing something].
- [This] no longer does [that], so you don’t need to do [something else].
If you’re ever in doubt, you can always ask a non-technical person to read them over.
Release Notes Mistake #2 – They’re Too Vague
Many tech giants have embraced vague release notes (inadvertently). According to engineers on a popular Reddit thread, release notes for large companies are complicated by the requirement to translate into various languages and address different types of users. The good news is that smaller companies or less technical projects don’t face these same requirements.
Good release notes should be short and concise—not vague.
You can improve your release notes with a simple process:
- Start with a list of new features and/or bugs in a release.
- Pare down the list to the most important and impactful changes.
- Read through the explanation of the change and rewrite it into a bullet point or short paragraph that succinctly explains the utility to the user.
Of course, the right level of detail depends on the audience. The release notes for an engineering application may mention very specific code-level changes whereas the release notes for a consumer-facing app may keep things relatively high level.
Release Notes Mistake #3 – They’re Too Long
Tech giants may end up writing vague release notes, but other companies have the opposite problem—a laundry list of changes in each release notes. While it’s easy to copy-and-paste changes from development tools, users can’t be expected to scroll down pages of bullet points to find the ones that interest them—release notes should be approachable and easy to read.
Amoeboids-Ways-to-Promote-Release-NotesThere are several ways to cut down on your release notes:
- Create different sections, such as “New Features” and “Bug Fixes”, to help users find the changes that interest them more quickly.
- Link to blog posts, support articles or other documentation to expand upon changes rather than explaining them in the release notes.
- Rewrite the rewrite until a change is concisely explained in a single bullet point or a very short paragraph.
It’s important to remember that release notes aren’t the only way for users to discover new features or bug fixes. If you want more exposure, you can introduce a new onboarding sequence, write a blog post or send an email to further promote the change.
Release Notes Mistake #4 – They’re Hard to Find
Everyone is familiar with release notes on the App Store or Google Play where they’re prominently shown on the app page, but it’s much harder to find release notes for desktop applications or software-as-a-service apps. In addition to writing good release notes, product managers must ensure that they’re actually seen by users.
There are a couple common ways to improve visibility:
- Add in-app notifications that highlight new changes following a release. For instance, Automated Release Notes for Jira provides an easy-to-use widget and a dedicated release page to inform users of new changes.
- Marketing efforts, such as newsletters or blog posts, can be a great way to showcase important changes. For example, you may want to announce new features in a dedicated blog post that explains how to use them.
It’s equally important to ensure that release notes are shared with the right internal audiences. Using tools like Automated Release Notes for Jira, you can easily configure release notes to automatically send to important stakeholders via email or other methods.
Examples of Good Release Notes
Release notes should be short and concise using plain language that is easy to read and understand. That said, many companies show their brand and personality in their release notes, which can help make them even more compelling to actually read.
Let’s take a look at a couple well-written release notes that you can use as inspiration.
Slack
Slack’s release notes are segregated into “What’s New” and “Bug Fixes” with concise bullet points. The company also writes its release notes with some humor in a way that makes them enjoyable for users to read without sacrificing readability.
Things
Things release notes include a bulleted list of changes, as well as a section that promotes new features. Rather than outlining every new feature, the company links to their blog where users can read about the new details in a more interactive format.
The Bottom Line
Release notes are often an afterthought during the development process, but they can be a valuable way to increase loyalty and retention. If your process suffers from the four most common release notes mistakes we’ve outlined, you may want to consider revising the processes. That will be a step in the right direction to make your release notes more engaging and effective.
