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:
- 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.
That’s about all I can come up with for now. Do you have any thoughts?
Posted on 19 August 2017, in technical writing. Bookmark the permalink. 9 Comments.
Sarah, this is a great primer. One thing I would add from my perspective: I write about hardware systems with multiple components. Any time a bug fix is required for any of the components, some or all of the other components will require a firmware upgrade. So one thing I always include in the Release Note is a table showing firmware versions required for all components. Each has its own specific version.
Thanks Jim, that’s a good perspective.
Navigation was a part of the release notes I’ve worked on over the years. At one company, the RNs were structured like the menus in the systems; at another, there was a column dedicated to navigation instructions (Path1 > Path2 > Path3). Our upgrades happened quarterly and often the users who ‘handled’ the upgrades were rotated (plus personnel changes). Thus, our baseline use case was that the reader of the RNs was someone who was brand-new to the system, had no idea where the described functionality could be seen, and didn’t have time to ‘discover’ or ‘play’ in the system.
That’s an interesting perspective. Did you pick some of the most common use cases to determine the paths in the release notes? It’d be great to see an example – are any of them available online?
9 times out of 10, we were dealing with a single path to the screen that had been changed. In those rare instances where there were multiple paths, we would just list them.
One other thing I was going to mention is the idea that the release notes shouldn’t read like they were created by different people. There should be consistency in the verbs and text used to describe changes to the system. For example,
Dave wrote this text to describe a change to a system:
“Modified the program to ABC” (where ABC is an action)
Ken wrote this text to describe a change to the same system:
“The program was altered to allow the user to XYZ (where XYZ is an action that is not the same as the ABC action in the other blurb)”
Karen wrote this text to describe a change to the same system:
“When the program encounters records with the MNO field set to QRS and the system value is set to PPP, the [name of program] will now process these records. Previously, this would generate an error report that would be sent to your spooled files and you would have to go through the errors that had been listed on the report to then go into the [name of a different program], located on the [Path1 > Path2] and make changes before returning to this menu option and rerunning it.”
I argued that, aside from the second blurb being passive and the third example being horribly constructed, it read like there were different people writing the text. The user just wants information – how does this change impact my daily work? Sadly, the egos of 3 non-writers got in the way of allowing me to edit the RNs at that company.
Release notes should answer at least 3 questions. What has changed/ is new? How does this impact me? What do I do differently because of the change? It’s good to use a template. Will ensure that at least minimum (and consistent) information is being captured by whoever is writing the notes.
Hi Sarah. Great article! We try to keep our release notes simple and easy to read for our users and usually include visual elements to better explain the new feature or update. We use a tool called Beamer (www.getbeamer.com) that has helped us a lot with this.
Thanks for the link. Beamer looks pretty interesting. I see they have an API as well as an embeddable widget, the release notes tool, and more.
Funny: When I go to Product on their page, and then click Release Notes, I expect to see their release notes, not the release notes product. 🙂
Pingback: The art of writing great release notes – Documenter.co.uk