Skip to main content

How to Write Release Notes – The Right Way

Posted by Andrea Saez
June 1, 2016

Why are good release notes 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.

https://twitter.com/auermi/status/730545482213138432

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.

How to write release notes

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:

release notes template

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 notes, complete with emoji:

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.”

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?

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 Comments
Inline Feedbacks
View all comments
June 3, 2016 8:57 pm

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.

Patrick
September 3, 2019 11:32 am

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.

[…] 7. How To Write Great Release Notes | ProdPad […]

[…] that reason, as Adam Sigel at InsightSquared explains on this excellent ProdPad blog post, “most people don’t read […]