We know what you’re thinking: Release notes best practices? Good grief! Like I don’t have enough to worry about, making sure my product roadmap always reflects our current strategy and that my backlog doesn’t become a black hole of endless to-do items and product ideas. So now I have to make sure our release notes are following the best practices formula? Does anybody even read product release notes?
You make some fair points. But yes, some people do read release notes. And when it comes to your company’s products, those people are your customers.
Release notes represent an opportunity to communicate with your customer base.
Of course, few companies take advantage of this opportunity. Release notes have become the product-update equivalent of Terms & Conditions and Privacy Policy statements. They’re written so poorly, with such little regard for the actual human being who must read them, that we’ve all learned to ignore them.
So before we get into our advice for release notes best practices, let’s briefly review some of the worst practices.
3 Reasons So Few People Actually Read Release Notes
1. Release notes written in technical language
Yes, release notes typically describe technical updates to the product. But that’s no excuse for writing them in developer-speak.
What are we supposed to learn from an app’s release note that tells us: “Plone instance trouble ticket #34701 failover issue resolved?” Unless you’re the user who submitted trouble ticket #34701, you’re probably going to find that update useless. Yet this is how many organizations write and publish their release notes.
2. Vague release notes
Another common problem with product update release notes is they don’t tell us much of anything.
You’ve probably seen release notes with helpful updates like: “Various improvements and performance enhancements.” Oh. Cool, I guess. I’m sure it’s good news, whatever that means.
Or worse: “v3.0.11.2 addresses several security issues.” Well, thanks, but which ones? How long did your app have those security issues? Could my data have been compromised during that time? Also, when you say “several” issues, do you mean the app still has more security vulnerabilities that you haven’t fixed yet?
3. Release notes that are too long
We won’t bore you with an actual example here, but you’ve seen them plenty of times—the release notes that go on and on forever. It’s usually all smashed together in one huge block of text, so it’s not even easy to figure out where one note ends, and the next begins.
Why would a company do this? Why would they scribble out a bunch of words they know will be meaningless to the vast majority of users who read them?
Because organizations are busy, product managers have many on their plates, especially when they’re readying a product release. And the release notes that accompany those product rollouts never seem like a high priority.
But like we said, that’s a missed opportunity for great communication with your user base.
The 404 Error Example
The common “page not found” error offers another helpful example of what we’re talking about. Chances are, most of the time, you encounter an error message when you try navigating to a web page that can’t be loaded; those pages look like this…
Not exactly awful. But it’s also a missed opportunity to make a real connection with the site’s visitor. For example, look at how the Disney website treats a visitor who requests a page that the site can’t load…
Even though they can’t access the page, they were looking for, and users won’t find this moment a total loss because Disney has treated them to a fun little gift, one that’s totally consistent with their brand.
You can think of your product release notes similarly. Yes, many of your users won’t ever read them (just as most visitors to the Disney site won’t ever find this page). But when you publish those notes, why not make them as readable, interesting, and fun for your customers as you possibly can?
(By the way, if you’d like some ideas and inspiration for making your site’s page-not-found message more engaging, check out this great CreativeBloq post on brilliantly designed 404 error pages.)
Now, as promised, here are some release notes best practices.
5 Release Notes Best Practices
1. Use plain language
Leave the techno-jargon out. Write your release notes like you are explaining them to a friend. Preferably one with a degree in history or anthropology, not in computer science.
2. Keep them short
If you’ve added a new integrated calendar into your app that users can access on the main dashboard, great. Just say so. It shouldn’t take more than a sentence or two to explain it. Don’t turn release notes into a novel.
3. Group them logically
If we pop open the release notes accompanying your latest product release, show us immediately—with big, bold category headers—what we’re getting in the new version. Show us FIXES, IMPROVEMENTS, NEW FEATURES, etc. So we can zero in on the areas that interest us most.
4. Include relevant links
If you’ve got a new feature, your release notes should contain a high-level summary of what it can do and where to find it. But, of course, we might want more info, so give us a link to the detailed stuff, like a user guide, step-by-step walk-through, or even a video tutorial.
5. Show your company’s brand and personality
As Sami Linnanvuo suggests, release notes can represent a chance to create engaging content for your community of users and deepen your relationships with customers.
Their article on MindTheProduct, they link to some great release notes from companies like Slack and Trello, who present product updates in engaging ways.
Slack, for example, included this update in the release notes accompanying its version 1.99:
“Fixed: A crash would occur on launch if a highlighted word matched an emoji. This was emojiist and has been remedied.”
4 Release Notes Examples
If this is your first time writing release notes – or maybe you’re looking to make the release notes you do write even better – a great place to find inspiration is through a few quality examples. Here are some of the best release note examples we’ve seen from companies who know how to tell a product story.
1. Intercom
There are so many good things going on in Intercom’s release notes. Before we even mention the actual release notes themselves, notice the URL they use: www.intercom.com/changes/
Framing release notes simply as “changes” is a great way to reduce unneeded formality and get to the heart of the purpose release notes actually serve. First, they’re a list of changes. Second, they speak to how the product has changed and grown over time.
If I’m a user, do I want to read “release notes”? Meh, maybe not. But do I want to read about product “changes?”
Absolutely I do.
It’s a small shift but can have a profound effect on a user’s desire to engage. In fact, rejecting formality in favor of personality is a theme throughout Intercom’s release notes. We see emojis in the title. We see a way to voice user opinion on each release through smiley faces (or frowny ones). And Intercom even showcases the engineers and product specialists who worked on the release. That’s a nice human touch.
All of this comes together to create a release notes example that not only informs but also sprinkles in moments of delight – just like the best products do.
2. InVision
Where Intercom excels in personality, Invision excels in detail. Just look at how robust their November 2020 release notes are. Not only do they track changes for several different products over time – including version updates – but they also have dedicated landing pages for each tool in case users want to dig deeper.
With all of this content, InVision makes sure users can quickly find what they’re looking for. Oftentimes, users may only use one iteration of a tool for a specific purpose. To that end, their release notes are organized by product, with a “what’s new” section at the top followed by “what’s fixed or improved.” Additionally, InVision keeps a menu hanging out on the top left of the screen so users can easily click on the sections that matter most to them.
To top it off, their release notes are littered with links to various support documentation and help articles that ensure users are never at a loss for what to do with a particular update.
3. HubSpot
Release notes don’t have to be confined to a blog post or support article. In the case of HubSpot, they’ve created product spotlight videos that take their users on a tour of how the product has grown over the course of the last month. You can watch the entire video for a rundown of everything new or skip to the sections you care about most with the handy timestamps HubSpot lists below.
Of course, more traditional, written release notes are there too if you prefer, and they are excellent. In addition, HubSpot does a great job of building tutorials for how to use a new feature-complete with screenshots. These serve as a launching pad for users to get back into the product and try out all the new things HubSpot offers.
4. ProductPlan
Last but not least, we have our own release notes.
In truth, we made a conscious decision to improve our release notes in recent weeks. Previously, our release notes were a simple list of new features, enhancements, and bug fixes often copied from our engineering team and then spruced up with some marketing language.
It’s a great place to start. We’d argue those are the three components every release note needs to serve its basic function: quickly informing users about changes in the product. But at the same time, we felt it lacked some of the qualities we love about the other release note examples showcased above.
So we’ve worked to make a few enhancements of our own. The title of each release, previously just named according to the day it was released, highlights the most important part of each new release. We kept the lists of features, enhancements, and bug fixes but appended to it a little bit of story for why we’ve released the features we have. It helps contextualize the importance of each feature while giving our users a sense of where the product is going, what we’re prioritizing, and the kinds of feedback we’re hearing. It’s also simply more interesting to read.
We also decided to upgrade the visual experience of our release notes with animated GIFs. Especially when a release includes a new user flow or clicks path, it’s important to illustrate how users can access new features and enhancements.
As you look to write your own release notes or improve the ones you already write, these are some of the small improvements that can make a big difference.
Treat Your Release Notes Like They’re Going to Be Read
Release notes might not seem important, but they are part of your product. And just like each new release of the product itself, release notes go out to all your users. Our advice? Treat them with respect. And view them as opportunities to communicate with your user base and your broader market.
