Skip to main content

How to Write Release Notes – The Right Way

June 1, 2016

5 minute read

Why are good release notes examples so hard to come by? Why are they so rare that I take a screenshot whenever I come across one that manages to be readable and fun? Not everyone has caught on to the hidden value of writing really great release notes.

It’s the only thing that can explain why teams at companies like Slack and Citymapper are elevating the release note to an art form, while others just write up half-assed notes.

But you don’t have to make your release notes a work of art to take advantage of a great engagement opportunity.

Just write better release notes.

The hidden value of great release notes

Not everyone reads release notes, but the people who do read them matter.

Adam Sigel, Product Manager at InsightSquared, says this about release notes:

“Release notes are a really interesting engagement opportunity to me. Most people don’t read them, but those that do represent a highly targeted audience of very engaged users. Every company with an app has to write them, and I love to see who treats it like an opportunity instead of a chore.”

That’s because those who pay attention to release notes are vocal about how their experience hasn’t matched up to their expectations. On the flip side, they tend to give high praise for a job well done.

Emmanuel Quartey of Meltwater has documented some excellent examples of customer comments about release notes on social media. He attributes this to their high level of emotional investment in the products they use:

“These are the people who’re getting the most value from your product, who’re emotionally invested in your team’s success, and who need to be incentivized to tell all their friends about what you’ve made.”

You may think users aren’t waiting for updates, but you’d be surprised at how even minor changes can provide a unique experience to your product. People do notice.

They may even be willing to provide you with feedback if only you would tell them what you’ve released.

If a user is waiting for a specific improvement or functionality, it’s easy to see why they would get worked up over a release note like this:

release notes example linkedin
Come on, LinkedIn.

In this screenshot, LinkedIn doesn’t connect to people or opportunity. It just sits there, communicating nothing.

‘Bug fixes and performance improvements’ is meaningless. What did they fix? How will performance improve? Where in the user experience can we expect improvements?

A missed opportunity to say the least.

Release Notes Examples

Good release notes are written to be read, clearly outlining what has been improved and its benefit to users.

I find release notes easier to digest when they’re divided into sections. Sections make for easier scanning, and they’ve also helped me organize myself while I write.

Here’s the template I came up with at ProdPad:

How to write release notes - Release notes example
Release notes example

Writing clear, specific release notes mean you can open up communication with your customers on the progress of your product.

It’s useful for potential customers too. They often ask whether we publish release notes – probably because it’s a good indicator of whether we’re delivering what we promised on our roadmap.

It’s no secret that we’re a fan of public product roadmaps, and we encourage you to make your release notes public too. They will bring you the same benefits.

At ProdPad, I make sure our release notes are accessible from all our major touch points. These include our app, our Help Center, our internal Slack and our customer’s Slack community.

Customers love commitment to transparency – it gives them a reason to trust you.

Our release notes tend to be specific and benefit-driven, which shows customers we’re writing for them. As a result, they come talk to us, which is exactly what we want!

Here’s one of my recent release note examples, complete with emoji:

Best release notes examples

Use everyday language

After a number of discussions, the Slack team finally agreed on what their release notes should look like:

“They should take the basic facts, reduce jargon, put them into words people could relate to; words that might be lightly poetic and slightly absurd, but stopped short of grating, and…nothing less than informative.”

How to write release notes. Slack release notes example
Slack’s release notes are wonderful.

Notes like this don’t just happen. Slack points out that its whimsical-but-practical technical writing style doesn’t come easy for all its dev teams.  So each one goes through a review process with an editor to check for style, accuracy and readability.

Embrace your brand personality

“In 2015 Medium delivered updates to its app via a country ballad, a series of haiku, a eulogy, Kenny Loggins song titles, and a faux Slack conversation,” reports Verge editor, Casey Newton.

Medium gets to be fun and experimental. It’s a reflection of the brand, its purpose and the people who make up the organization.

In fact, when Newton was invited to Medium’s HQ for beers and release note writing, he found that two employees did most of this work. They were Nick Fisher, Medium’s community manager, and Greg Gueldner, a member of the company’s trust and safety team.

Says Newton: “[Fisher and Gueldner] note that the release notes are consistent with Medium’s general purpose of inspiring creativity. It isn’t the only company to treat release notes as performance art… but for sheer gonzo ambition, Medium leads them all.”

Medium uses its own storytelling medium to explore new, offbeat ways to communicate its new releases.

What would your brand do?

Enjoyed this article? Check out our product management blog for more key insights.

Sign up to our monthly newsletter, The Outcome.

You’ll get all our exclusive tips, tricks and handy resources sent straight to your inbox.

How we use your information

6 thoughts on "How to Write Release Notes – The Right Way"

  1. Great post, Andrea. I’ve been following the release notes of Slack in particular because they’re awesome, and they did a nice blog post on theirs as well (https://slackhq.com/a-little-thing-about-release-notes-997d2e06842d#.eyo5397i3), but I like your template even more.

    Also, super important mention of brand at the end there… here at Sight Machine I don’t think we could get away with being so cute/light-hearted/whimsical (tell me if you disagree). We need to appear a bit more serious… but there’s still room to reflect our brand in the style and make it worth someone’s time to read.

    1. Hey Harry,
      Glad you liked the blog post! And I totally agree – not everyone can necessarily get away with being funny, but if you can, why not? At the very least they should be clear, concise, and in simple language everyone can understand. There are still ways to push through the brand personality without the funny bits, but I still think the most important aspect is to make them comprehensible and easy to read.

  2. Hi Andrea! Good post. We’ve actually left behind the long, technical release notes and replaced them by shorter announcements, with pictures, videos or GIFs and call to actions for our users to go directly into the new feature/ release. The results were amazing! We found a tool called Beamer (www.getbeamer) to post our release notes very easily, which I really recommend.

Comments are closed.