Blog Home
Writing Great Release Notes: A Step-by-Step Guide
Almanac Team
Almanac Team
6.30.2022
min read

What are release notes?

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:

  • What has changed in the latest version of your product?
  • Why has that thing changed?
  • How does this change impact the user?
  • What does the user need to do differently as a result?

If you answer all of those, you can’t go far wrong.

Why care about release notes?

They engage with your best users

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.

People read them

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.

How to write great release notes

To write release notes:

  1. Consolidate developer notes
  2. Edit them to remove jargon and rewrite in concise English that customers can understand

To write great notes, start with the principles below.

Be human

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

Think about visual design

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):

  • Using bullet points.
  • Creating titles that stand out.
  • Adding spacing so users aren’t faced with a wall of text.

Reward people for reading them

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.

How to avoid common mistakes when writing release notes

Don’t be too creative

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

Don’t sacrifice utility for humor

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

When not to write release notes

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:

  1. Facebook makes so many changes that describing each one is overwhelming
  2. It was easier to provide in-app walkthroughs than putting blurbs in the App Store

We’d suggest avoiding release notes if:

  1. You’re brand new. Early on, things are always changing, and no one’s reading your notes anyway.
  2. No one reads them. Look at your data. If no one is reading, stop writing.
  3. You can share updates in the product. If, like Facebook, you invest in the ability to spotlight new features through in-app notifications, you can get more engagement and uptake, and avoid release notes.
  4. You’re too big. If, like Facebook, you make so many changes that release notes would be overwhelming, they may be a waste of time.

You Might Also Like

Join a live demo of Almanac
Learn how Almanac works in under 20 minutes.
Save my seat