Release notes (sometimes called the changelog or app updates) comprise the documentation sent out with the latest update or version of your product to inform customers what's changed and what's new in the release.
The most important function of release notes is to let customers know that something has changed in the product, particularly when that something may affect the way the customer uses the product. The change may be a new feature in the product, an entirely new product, a change to the way the product works, a change to the way the customer uses the product, the removal of a feature, or even the deprecation of the entire product.
Some key questions to think about when writing release notes are:
If you answer all of those, you can’t go far wrong.
Release notes have historically been quite dry and technical, with little effort made to engage with customers. However, they have experienced something of a renaissance in recent years, with more and more companies using release notes as an extension of their brand’s voice and an opportunity to engage with customers.
Hometap head of product Adam Sigel said he looked forward to app updates not only to find out what new features might improve his user experience, but also because he hoped to find something good to read:
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.
Head of growth at Paystack Emmanuel Quartey added: "App update release notes are a very small user touchpoint, but with just a little bit of imagination, they can be a way to connect with users on a whole other level."
While some companies have started to use release notes as a small platform for expressions of creativity and comedy, it’s not an entirely risk-free art form.
One of our contributors ran a survey to see how many people actually read release notes, how regularly they read them, and why they read them. The results were a lot higher than we thought they would be:
At the time of writing, he had 364 responses, with 83.2% saying they read release notes or app updates.
To write release notes:
To write great notes, start with the principles below.
When writing release notes, remember that you’re a person speaking to another person. It’s another layer of user experience that helps you connect with your customer on a human-to-human level. For example, “We are doing X for you.”
Most of the focus typically goes on the content of release notes, but it’s also worth considering the visual design of your release notes. Some companies are going the extra mile to make their release notes visually interesting. GatherContent has a color-coded, interactive updates page:
Similarly, Todoist use different emoji as visual aids to inform their customers of the different types of changes in each release:
Product designer Rob Gill wrote a brilliant post about release notes design in which he advocates (among other things):
Release notes are a great opportunity to reward loyalty, especially as the people who read them are more likely to be your most dedicated and loyal customers. PolyMail took this approach and rewarded users who read their release notes with stickers:
PolyMail co-founder Brandon Shin, who wrote about how they make release notes more exciting in this post, said: “We looked for more ways to grow this feeling of appreciation and interaction. Sometimes we tucked in small prizes in the release messages, giving stickers to people that always took the time to read through.”
It doesn’t have to be a physical reward. Citymapper recently rewarded readers of their latest update by telling them about their new transport pass to save money in London.
Speaking at the Write the Docs conference, technical writer Anne Edwards felt that “funny, quirky, and friendly” release notes were often too wordy and either obscured the main message or created more work and confusion for the reader (especially for non-native English speakers).
She raises some valid points. However, when Tumblr produced a release note that was basically a 471-word fanfic-style story featuring its founder David Karp, it went viral and featured in the Guardian newspaper and Business Insider:
Some people might not have found that release note very helpful because it contained no information about what was actually in the release, but it demonstrated the power that a humble release note can have as a marketing tool.
Medium is another company that is creative and off-the-wall with their release notes, no doubt a reflection of their mission to inspire creativity in the millions of people who use the platform. Medium’s release notes have appeared in the form of haiku, a fake Slack conversation, song lyrics, and even an ASCII picture of a bug:
However, even the Medium writers behind the release notes admitted they were having to reign in some of the creativity of their content because users wanted more details about what was in each release version. In an interview with Verge, Medium’s community manager Nick Fisher said: "The most common blowback we get is from people who want to know what’s in the release. They hate these because they have no idea."
There is sometimes a fine line between being funny and being annoying, so it’s no surprise that some companies have started to come under fire for being too irreverent with their release notes. People don’t always appreciate jokes or zany content if it doesn’t also provide any meaningful update about the product they’ve invested their time and money in.
In her Tech Crunch article “App Release Notes Are Getting Stupid”, writer Sarah Perez said she felt some companies were being irresponsible and disrespectful to customers by not providing decent information in their release notes: "This inattention to detail is a disservice to users, who no longer have the benefit of understanding what the updated app will now do — or not do — as the case may be […] They don’t know what functionality has changed or how the user experience is being affected. They don’t know if the changes are even bad or good."
She continued, “At the end of the day, if a developer wants to have fun with the release notes, that’s up to them. But no matter what, they should still feel a responsibility to their customers to communicate what’s being installed on the end-users’ devices.”
Slack felt the need to apologize for their overuse of humor a few years ago, but in general they’re good at striking the right balance between providing release notes that are both funny and useful to the end-user
You don’t necessarily need release notes. Facebook took the somewhat controversial decision to no longer produce detailed release notes and produce in-app notifications about new features and changes instead. It wasn’t popular with some users:
Amidst the backlash, a Facebook engineer posted on the MacRumours website to defend the decision, saying:
