How to Write Release Notes – The Right Way
Why are good release notes so hard to come by? Why a
re 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.
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.
— Niall O’Kelly (@niallokelly) December 6, 2014
— Abishek Muthian (@Abishek_Muthian) May 31, 2016
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:
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:
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.”
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
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?