How to write release notes

Release notes, sometimes called a changelog, let customers know when something’s happened in or to a product that could affect them. Various groups of people are involved in creating the release notes. Sometimes it’s hard to know what to include in the release notes. Here are some thoughts from me, after writing release notes for different types of products over the last few years.

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.

Examples of release notes

Atlassian creates comprehensive release notes for the major releases of each product, with graphics to illustrate the major features. For example, take a look at the Confluence 6.0 release notes. The minor releases list the issues resolved.

The Canvas release notes are full of information, including graphics to illustrate the top updates.

Release notes at their most minimalist are often called a changelog. A good example is the page for the Google Maps Android API. For a major release, the team includes screenshots and a tutorial on the Google Maps APIs Blog as well as in the documentation.

Some products support a complex set of variations in platforms and languages, as you can see in the Debian release notes.

Chrome DevTools kick off their release notes with a video and plenty of graphics.

Who writes the release notes?

Often, a technical writer creates the release notes based on input from product managers, engineering teams, marketing advisers, and other stakeholders.

In other cases, a various teams write or contribute to the release notes. For example:

• The engineering team may write the simpler release notes, such as minor releases (point releases) consisting of bug fixes.
• Product managers or marketing managers create the content for major new features or product launches. This is particularly so if the organisation’s primary promotion channel is a blog. A case in point is the Google Maps APIs Blog, which I mentioned earlier in this post.
• A developer relations team may write software samples that illustrate a new feature in an API, and a video illustrating the new capabilities.

Letting customers know about the release notes

It’s a good idea to ask how customers will discover your release notes. It’s unlikely they’ll come and check your site regularly, just to see if something’s happened.

Here are some of the ways you can let customers know that you’ve published new release notes:

• Provide an RSS or Atom feed on your release notes. For example, the release notes page for the Google Maps JavaScript API provides an Atom feed, updated each time the release notes are updated.
• Write a blog post about major updates and other happenings that your customers need to know about.
• Offer email subscriptions for your release notes and other product news.
• Set up social media accounts for your organisation, and announce product news via those accounts. This tactic is useful if you know where your customers are likely to see the news. Examples are Twitter, Facebook, Reddit, Instagram, and more. For an example of indepth use of a particular platform, take a look at my post on using Twitter as medium for release notes.

An important point is to make sure there are links to the technical documentation from the release notes, blog, Twitter, and so on. The links help customers find the information they need after reading an overview of the new features/products. The links also boost the search engine optimisation (SEO) of the documentation, and let the customers know the docs exist as a good source of information.

What to include in the release notes

New features and products. Let people know about new features that enhance their use of the product. Provide an information-rich summary of what the feature means to the user, and how they can start using it. An illustration is good idea. Depending on the product, the illustration could be a screenshot, a photograph or video, a diagram, or a code sample. Also include a link to the documentation where people can find more information. If the feature was requested by customers and the feature request is publicly visible, link to it so people can see you’re listening to their requests.

Bug fixes. Include a list of the issues fixed in this release. Link to the documentation for further information where relevant. If the bug report is publicly visible, link to it so people can see you’re responding to their reports of problems.

Upgrade guide. Note any steps people need to take when moving from the older release to the newer release of the product. In some cases, there may be significant steps required. The nature of those steps depends on the type of product. For example, if the product is an API, the developers using the API may need to change their code. If the product is a software application, the system administrators may need to adjust configurations and update other applications that interface with or integrate into the updated application.

Deprecations and turn downs. Highlight any product and feature deprecations, and let people know when a product is turned down for good. A deprecation is a notice to customers that a feature or product is no longer recommended for use, and will or may be taken down at some point in the future. If there’s an alternative product or feature, let customers know where to find information about it. If possible, provide a migration guide telling people how to move from the deprecated feature to the new feature.

Other notes. Put yourself in the shoes of the user, and add the information you’d find useful. These notes may come from UX testing of the new feature, internal testing of the upgrade process, knowledge of customers’ procedures from the technical support engineers, or other sources.

Is a template useful for the release notes?

You could consider creating a template, to ensure that each update to the release notes follows a common pattern. Often though, the previous set of release notes is a good enough guide.

A template may also be a good idea for collecting information from stakeholders, but beware the content bloat that happens when people feel they need to supply words to fill a gap. Release notes should be lean and information rich.

More?

That’s about all I can come up with for now. Do you have any thoughts?