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 and reading through 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”, 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.”

At least they were honest!

“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 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.
Photo by Maliha Mannan on Unsplash

Hometap head of product Adam Sigel said he looked forward to app updates to not only find out about new features 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

However, speaking at the Write the Docs conference, technical writer Anne Edwards said she 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 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 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 irreverent so it’s no surprise that some companies have started to come under fire for 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.

 

https://twitter.com/jaredsinclair/status/633407338347634688

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 version of their 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 changes

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

GatherContent’s release notes contain an animated bug!

Similarly, Todoist use different emoji as visual aids to inform their customers of the different change types in each release, using a ⚙️ for improvements, 🐛 for bugs and ⭐for new features:

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

  1. How to write a release note — Sarah Maddox (Google technical writer): https://ffeathers.wordpress.com/2017/08/19/how-to-write-release-notes/
  2. Great Release Notes — Adam Sigel (April 19th 2015): https://medium.com/@adamsigel/great-release-notes-508b5f74989e
  3. 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
  4. Learning to Love Release Notes — Anne Edwards (September 2018) http://www.writethedocs.org/videos/prague/2018/learning-to-love-release-notes-anne-edwards/
  5. 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
  6. 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/
  7. A little thing about release notes — Slack Blog (April 4th 2016): https://slackhq.com/a-little-thing-about-release-notes
  8. As a Designer I want better Release Notes — Rob Gill (March 3rd 2017) https://uxdesign.cc/design-better-release-notes-3e8c8c785231
  9. 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/
Advertisements

Will AI reduce the need for technical writers?

The late Stephen Hawking famously said that artificial intelligence would be “either the best, or the worst thing, ever to happen to humanity.” As a technical writer documenting AI technology, I’d like to believe it would be the former and it’s fair to say there have already seen positive signs about how AI might shape and assist with documentation in the future.

A number of tech companies have already dipped their toes into the water, with some developing AI-assisted, predictive content generation and others harnessing machine learning to predict the help content the end-user is looking for.

AI-assisted content

Google introduced its natural language processing development, Smart Compose, to help Gmail users write emails in May 2018. They combined a bag-of-words (BoW) model with a recurring-neural-network (RNN) model to predict the next word or word sequence the user will type depending on the prefix word sequence they wrote previously.

model3
The Smart Compose RNN-LM model architecture.

Smart Compose was trained with a corpus of billions of words, phrases and sentences, and Google carried out vigorous testing to make sure the model only memorised the common phrases used by its many users. The Google team admits it has more work to do and is working on incorporating their own personal language models that will more accurately emulate each individual’s style of writing.

Arguably one of their biggest challenges they face is reducing the human-like biases and subsequent unwanted and prejudicial word associations that AI inherits from a corpus of written text. Google cited research by Caliskan et al which found that machine learning models absorbed stereotyped biases. At the most basic level, the models associated flower words with something pleasant and insect words with something unpleasant. More worryingly, the research found the machine-learning models also adopted racial and gender biases.

f1.large

The research found that a group of European American names were more readily associated with pleasant than unpleasant terms when compared to a batch of African American names. Researchers also found inherited biases included associating female names and words with family and the arts while male names were associated with career and science words. Yonghui Wu, the principal engineer from the Google Brain team, said: “…these associations are deeply entangled in natural language data, which presents a considerable challenge to building any language model. We are actively researching ways to continue to reduce potential biases in our training procedures.”

AI-assisted spelling and grammar

With 6.9 million daily users, one of the most common tools people are using to assist the accuracy of their spelling and grammar is Grammarly. The company are experimenting with AI techniques including machine learning and natural language processing so the software can essentially understand human language and come up with writing enhancements.

crisp-writing-alter-ego-communications

Grammarly has been training different algorithms to measure the coherence of naturally-written text using a corpus of text compiled from public sources including Yahoo Answers, Yelp Reviews and government emails. The models they have experimented with include:

  • Entity-based model – Tracks specific entities in the text. For example, if it finds the word “computer” in multiple sentences it assumes they are related to each other.
  • Lexical coherence graph – Treats sentences as nodes in a graph with connections (“edges”) for sentences that contain pairs of similar words. For example, it connects sentences containing “Macbook” and “Chromebook” because they are both probably about laptop computers.
  • Deep learning model – Neural networks that capture the meaning of each sentence and are able to combine these sentence representations to learn the overall meaning of a document.

Although this is still a work in progress, their long term goal is for Grammarly to not only tell you how coherent your writing is but to also highlight which passages are difficult to follow.

AI-assisted help content

Some companies have started to look at ways that AI can help with predicting and directing readers to the exact content they are looking for. London-based smart bank Monzo launched a machine-learning powered help system for their mobile app in August 2017.

monzo

Their data science team trained a model of recurring-neural-networks (RNNs) with commonly asked customer support questions to make predictions based on a sequence of actions or “event time series”. For example:

User logs in → goes to Payments → goes to Scheduled payments → goes to Help.

At this point, the help system provides suggestions relating to payments and as the user starts typing, returns common questions and answers relating to scheduled payments. Their initial tests showed they were able to reach 53% accuracy when determining the top three potential categories that users were looking for out of 50 possible support categories. You can read more about their help search algorithm here.

What does the future hold?

I think we will see more content composition tools like Smart Compose emerge but I think it will take a lot of time and work before they can be trained to effectively assist with the complex and often unpredictable user-oriented content that technical writers are tasked with producing on a daily basis.

datacenter-future-e1503509968416

I’m sure some technical writers are already using Grammarly to assist with their spelling and grammar. It can be a really powerful tool to ensure your text is not only accurate but in the future will be able to measure the coherence of your writing. I’ve dabbled with Grammarly but found it either wasn’t compatible with certain tools or prevented some of my applications from working so it became a bit of hindrance rather than an assistant for me personally. No doubt these are kinks they will iron out at some point down the line.

I do see the benefits of AI-assisted help so it would be awesome to see some more development in this area. It really could be something that saves customer support and documentation teams a lot of time in terms of predicting and directing end-users to answers before they’ve even asked a question.

So are we there yet? Not quite… but I think some very promising foundations have been laid. While some technical writers might be concerned, I think it will be a very long time before AI is advanced enough to supplant our role in the development teams. So don’t be afraid of AI, for the time being these tools are only going to make our lives easier!