The art of writing great release notes
One of the first tasks I was given as a technical writer was writing a set of release notes. For the most part it involved pulling together developer notes, removing jargon and rewriting the text in concise English that customers could understand.
More often than not, the release notes felt like a bit of an afterthought, a chore that developers put off until the very last minute. While it might sound fairly simple, writing release notes is an important and yet under-appreciated task that requires more skill, care and attention than it is sometimes given credit for.
Although it is still fairly common to find release notes that simply state “bug fixes and improvements”, companies are investing more and more time and effort in make their release notes stand out. So, what is the purpose of release notes? And what is the best way to write them?
What are release notes?
Release notes, sometimes called the change log or “app updates”, basically comprise of the documentation sent out with the latest update or version of your product that informs customers what has changed and what is new in the release.
Google technical writer Sarah Maddox gave the following advice about release notes:
“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 won’t go far wrong.
Although there are no official guidelines to writing release notes, there are some general principles you can follow to ensure your release notes are informative, readable and useful.
Make your release notes more engaging
Historically release notes have always been quite dry and technical, so not much effort was 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 to not only 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.
The risks of being 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 so either the main message was obscured or they created more work and confusion for the reader, especially for non-native English speakers.
She raises some valid points but 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 offered no details about what was actually in the release but it demonstrated the power that the humble release note can have as a marketing tool.
Medium is another company who are 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.”
Finding the balance between funny and useful
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 apologise for their overuse of humour 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:
Asana is another company that is recognised for funny and informative App Store release notes (see here, here and here). However, interestingly Asana also produce a more formal and straight-laced set of release notes on their website. Perhaps this is a good way to appeal to different audiences in your customer base.
Watch your language!
It might sound obvious but it’s important to be careful and professional about the language you use in release notes. At a previous employer, one of my developer colleagues wrote the following as a placeholder for one of the tickets for some internal release notes:
TBD - a shit tonne of configuration changesThe documentation team missed it and although we found it funny at first, our smiles soon dropped when we realised the release notes had gone out to a customer. The shit hit the fan so to speak 💩.
Remember to be human
Remember that you’re a person speaking to another person when writing release notes. It’s another layer of user experience that helps connect you connect to 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 pages visually interesting. GatherContent has a colour-coded, interactive updates page:
Similarly, Todoist use different emoji as visual aids to inform their customers of the different change types 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 that will save you money in London.
Do you have to use release notes?
Not necessarily. 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 particularly popular with some users:
Amidst the backlash, a Facebook engineer posted on the MacRumours website, to defend the decision.
“… to describe every one of the thousands of changes that go into our mobile applications each and every release, the plain fact is that is just impossible. Many changes are under the hood for performance and bug fixes.”
He went on to describe the difficulties of providing release notes for pieces of work on features that haven’t been released yet and argued it was easier to provide in-app walkthroughs rather than putting blurbs in the App Store.
“We’re not trying to keep secrets from you. There are just simply better ways of telling you what’s interesting when those features are ready for you.”
Do people actually read release notes?
Yes, apparently they do. I’ve also been conducting 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 I thought they would be:
At the time of writing I had 364 responses, with 83.2% saying they read release notes or app updates. I’ll write about my findings in my next post so watch this space!
Some takeaways…
Ultimately, release notes are totally subjective. Some readers just want the factual information, while others want to be entertained. My advice would be:
- Make your release notes engaging if it’s in keeping with your brand.
- Being funny and creative is fine but balance it with meaningful content.
- Take care with your language.
- Remember to be human.
- Don’t forget about design and spacing. Walls of text are not appealing!
- Reward your readers for reading them. It doesn’t have to be a physical reward — secret content or early access features are rewards too.
In the end it is up to you to get the style and balance that is right for you and your company but as long as your release notes provide users with meaningful and informative content, they’re definitely worth the time and effort.
Resources
- How to write a release note — Sarah Maddox (Google technical writer): https://ffeathers.wordpress.com/2017/08/19/how-to-write-release-notes/
- Great Release Notes — Adam Sigel (April 19th 2015): https://medium.com/@adamsigel/great-release-notes-508b5f74989e
- The one user touchpoint almost every mobile app ignores — Emmanuel Quartey (January 11th 2015): https://medium.com/product-notes/the-one-user-touchpoint-almost-every-mobile-app-ignores-94ecfaf990f6
- Learning to Love Release Notes — Anne Edwards (September 2018) http://www.writethedocs.org/videos/prague/2018/learning-to-love-release-notes-anne-edwards/
- I drank beer and wrote release notes with the Medium release notes team — Casey Newton (Verge, Feb 10th 2016) https://www.theverge.com/2016/2/10/10938420/medium-release-notes-drinking
- App Release Notes Are Getting Stupid — Sarah Perez (Tech Crunch, April 9th 2015): https://techcrunch.com/2015/09/04/app-release-notes-are-getting-stupid/
- A little thing about release notes — Slack Blog (April 4th 2016): https://slackhq.com/a-little-thing-about-release-notes
- As a Designer I want better Release Notes — Rob Gill (March 3rd 2017) https://uxdesign.cc/design-better-release-notes-3e8c8c785231
- Facebook engineer defends decision to stop producing release notes — Mac Rumours (October 15th 2014) — https://www.macrumors.com/2014/10/15/facebook-youtube-iphone-6-support/
