When Release Notes Go Wrong: A Cautionary Tale

Release notes are an often-neglected way to engage users. While it’s tempting to push minor releases with little fanfare, well-crafted release notes can reassure users that the application is constantly improving and encourage the use of newly released features. The key is striking the right balance between information and creativity to compel users to read.

Let’s take a look at two ways that release notes frequently go wrong and how to improve them to maximize engagement with your users.

Release notes are an often-neglected way to engage with users, but there are right and wrong ways to go about writing them. Click To Tweet

Tech Giants & Generic Notes

Generic release notes have become the status quo for most large tech companies. For example, Facebook, Twitter and Snapchat all mention little more than “bug fixes” and “performance improvements” in their release notes for end users. These generic release notes have become a contentious topic for both developers and end users.

Example of Generic Release Notes – Source: App Store

A Facebook engineer listed a few reasons for the trend towards generic release notes on a Reddit post, including:

  • Release notes are a tedious task for product managers and developers.
  • There are logistical hurdles to writing detailed release notes. For example, they may need to be approved and translated into dozens of languages.
  • Features may not be released broadly to everyone at once and there’s no point in putting in a release note for a feature that you can’t use yet.
  • Many users don’t even bother to read about new updates and features.

The consensus on the Reddit thread was that release notes are useful for small applications with a few changes but challenging for large, complex applications with hundreds of developers. Larger applications may be better off displaying user-specific release notes in dialogs that provide an explanation of the feature and allow the user to enable or disable it.

Tumblr & Medium’s Creativity

Generic release notes aren’t very informative for users, but overly creative release notes suffer from a similar problem. Some companies that don’t necessarily see the value in conveying new features or bug fixes in their release notes instead use the opportunity to write funny or simply meaningless content designed to entertain rather than inform.

Download our Release Notes Style Guide to help you come up with the right voice for your application’s release notes.

Tumblr famously produced a 470-word fan fiction-style story featuring its founder in one of its release notes. While the release note went viral on The Guardian and Business Insider, it didn’t contain any useful information about the release. These kinds of antics might be helpful for some marketing visibility but shouldn’t be the norm for release notes.

Example of Tumblr’s Long Release Note – Source: Twitter

Medium also became well-known for its off-the-wall release notes featuring haiku poems, song lyrics and even ASCII pictures. While Medium is known as a creative outlet, the release notes were a missed opportunity to promote new features. It may be a good idea to spruce up release notes with some of these elements but not at the expense of useful information.

Slack Strikes a Great Balance

The best release notes strike a balance between information and creativity. Rather than writing dry release notes that list features and bug fixes, the best examples inject subtle humour and personality that encourages users to actually read them. In other words, product managers and developers should write release notes that they’d want to read themselves.

Don’t forget to download our Release Notes Style Guide to help you come up with the right voice for your application’s release notes.

Slack provides arguably the best example of the mix between information and creativity with release notes like these:

  • “Sometimes, you could not exit full screen mode with escape on windows, which was wrong, because that’s literally what escape means. Now, it works.”
  • “Slack would sometimes crash when the user right-clicked to see the context menu. In context, that was unhelpful. So it no longer does that.”
  • “So now spelling correctly should come more naturally to us all (which is good, because “correctly” can be a difacult word to spell).”

The right style or personality often depends on the brand style guide. Slack’s humour is only one type of creativity—other applications may simply choose to speak more plainly about new features or benefits than technical release notes.

Streamlining the Process

The first step in improving release notes is determining the right voice and style. For instance, enterprise healthcare software may not be the right market for humorous release notes. The type and level of creativity (e.g. plain talk vs. humour) depends on the audience and there should be a clear guide for product managers or technical writers to follow.

The process of writing release notes differs between organizations. While developers may write them on small projects, mid-to-large sized projects often have dedicated technical writers that pull in changes from Jira or other project management tools before each deployment. Finding the right writers is key to striking the right tone and personality in release notes.

Automated Release Notes for Jira can streamline the process of writing release notes by triggering the aggregation of relevant Jira issues and compiling release notes from a template as part of the CI process. With the relevant information in hand, product managers or technical writers can focus on style and creativity rather than spending all of their time gathering the basics.

In addition to aggregating features and bug fixes, ARN makes it easy to distribute release notes to the right audiences. Release notes can be automatically sent via email, saved as PDFs, JSON or HTML, or sent into Confluence. There’s even a customizable widget that enables the display of release notes in-app to maximize user engagement.

Try Automated Release Notes for Jira today!

The Bottom Line

Release notes are often-neglected ways to engage with users. While the status quo has become mundane, Slack and other companies have shown that a little personality can go a long way. The right tone and personality varies between projects, but spending a little time writing release notes for the audience (rather than to check off a task) can improve engagement.

Share this article