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. Now I have to make sure our release notes are following a 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 just 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 just 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 just 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 a lot on their plates, especially when they’re readying a product release. And the release notes that accompany those product rollouts just never seem like a high priority.
Download a Day in a Product Manager's Life➜
But like we said, that’s a missed opportunity for a 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 times you encounter an error message when you try navigating to a web page that can’t be loaded, those pages look like this…

Example of a missed opportunity in a 404 page

Not exactly awful. But it’s also a missed opportunity to make a real connection with the site’s visitor. Look at how the Disney website treats a visitor who requests a page that the site can’t load…

Disney, pixar 404 page example

Even though they can’t access the page they were looking for, 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 in a similar way. 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. 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.

In 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 highlight word matched an emoji. This was emojiist, and has been remedied.”

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.