It's here!
The 2024 State of Customer Self-Service Report is now available.
Read the Report
November 18, 2020
xx min read

[VIDEO] Best Practices for Creating & Managing Release Notes (Part One)

Release notes are important and deserve your attention. This presentation covers two important subjects:

  • How to better create high quality, personalized release notes to improve customer confidence, satisfaction, and to attract new customers
  • How to break down barriers to managing and creating the following deliverables in complex environments:
  • Multiple product lines
  • Multiple versions
  • Multiple user types and audiences
  • Multi-language requirements
  • Multiple publishing media formats

The Dreadful State of the Status Quo

Release notes are a great way to attract new customers while increasing customer satisfaction and confidence. However, organizations often treat release notes as an afterthought, a box to be checked for a version to ship. This leads to deliverables that are barely informative (at best). For those who read them, they often raise more questions than they answer. Worse yet, they're frequently disconnected from the product documentation, leaving the reader no easy way to find the area in the documentation that addresses an update.

A Wasted Opportunity to Increase Revenue & Customer Self-Support

  • Release notes often drive product upgrade decisions
  • Customers want to self-serve support whenever they can
  • Release notes are often a new user’s first documentation-related interaction with the product

It used to be the case that only techies read the release notes. That has changed as users have become more tech-savvy and hungry for information. Users read them to determine why they might want to buy the product or upgrade to a newer version. It also provides an informative resource they can use to answer questions without having to contact support directly. Release notes help demystify changes and provide users the ability to see if a requested feature or reported bug has been addressed in the new version.

Since release notes are typically presented directly to the user when they begin using the product -- or after a version upgrade -- they're often a user's first documentation-related interaction with your software.

This Impacts Your Reputation, for Better or for Worse

Because release notes are the first documentation-related interaction your users have with new product versions, they stand to leave a lasting impression and can impact your organization's reputation.

Reputation Dynamics:

  • Drive buying or retention decisions
  • Impact referrals and reviews
  • Reflect your company’s culture

Remember, buyers do their homework– and they'll find out what other people think. Reputation is crucial, and people are becoming more vocal about their satisfaction (and dissatisfaction) with release notes. A quick Twitter search illustrates this point quite well.

The Good: Your Release Notes Cause Exemplary Praise

Naice. Always a sucker for good release notes. Love the release notes of @ixigo as well. @alokebajpai @rajnishkumar — g_c_mouli (@gcmouli) September 6, 2020 

The Bad: Your Release Notes Cause Passive Aggression

Good Afternoon to everyone except for companies that write "routine bug fixes and maintenance" in their app release notes

— Amber Britton (@TheAmberBritton) October 28, 2020

Not only are users reading the release notes, but they're making public statements to their peers and the world. Recommendations are one of the most powerful ways to attract new customers and retain existing ones, and release notes are opportunities for good recommendations -- or bad ones.

Defining & Achieving High-Quality Release Notes

In complex environments, the resources required for creating high-quality release notes can be burdensome. Due to this, they're often delivered as quickly as possible to little effect. Transforming release notes into a useful resource is the major step towards quality. Just like your documentation, release notes have to be informative and helpful to the user to be valuable.

With the right process and tools, we can significantly increase the value of release notes and leverage them to create happier customers. We can view this as a release notes maturity model with the increasing sophistication of release notes leading to increased quality:

Level One: Curated

Most companies do some curation on their release notes to make them more user-friendly. This process involves taking what is usually very technical information entered by developers and transforming it into something more easily understandable by the average user. For instance, the following technical description is transformed:

Reduced need for buffering in the video sub-system to improve performance when loading over high latency connections.

Would be re-written as:

Significantly improved quality of video for users without broadband/high bandwidth connections.

Proper curation is an important process since we must ensure that as much of the original meaning and information is preserved while still being digestible to the average user.

Curation can also be taken further by adding screenshots, videos, or links to documentation. However, it’s best to use these supplemental pieces only when you want to really highlight something special. Even then, linking to the documentation or other marketing materials is ideal.

Tip: Provide before and after screenshots for major changes when possible. The visual aspect breaks up the heavy text aspect of release notes and can add a ton of value.

Level Two: Organized

Users like to see release notes presented in an easily digestible manner. Typically, however, release notes are delivered as a long list, with little organization and assistance to help the user find what they are most interested in.

First users are most interested in what new substantial features were added, then what minor improvements were made to existing features, and lastly what bugs were fixed, this gives us a simple organization scheme for release notes: New, Improved, Fixed.


  • [Feature] Search can now be limited to just the files in a particular publication
  • [Feature] Assignments can now be assigned to a group of users


  • [Improvement] Search speed optimized for searching within a folder
  • [Improvement] Context menu options can now be opened with the ctrl+shift+c shortcut


  • [Fixed] Taxonomy now handles terms with special characters correctly
  • [Fixed] Removed double scroll bar on publishing screen


  • [Ops] Upgrades to SSL security performed
  • [Ops] Web servers upgraded to now allow HTTP2 connections

Advanced Organization for More Complex Situations

If release notes are substantially large, organizations should also consider sub-categories based on the area of the product affected. For instance, building off the previous example of New, Improved, Fixed:


Content Manager

  • [Feature] Search can now be limited to just the files in a particular publication


  • [Feature] Assignments can now be assigned to a group of users

Level Three: Integrated

Release notes are tightly integrated with other relevant content/systems:

Level Four: Personalized

With the right processes in place, release notes can also be personalized for particular product tiers, audiences, or even particular customers or partners. This level of personalization or conditionalization makes it easier for customers to find the information they specifically require. Providing personalized release notes can be a huge win for customers, especially in the enterprise space. This extra attentiveness to details your customers care about directly impacts customer satisfaction and retention.

At Heretto we tag content for various types of personalized deliverables. This allows us to automatically generate customized versions.

We also use this internally to create versions of release notes to progressively disclose information for internal and partner use. The internal release notes are still curated and organized well, but can also include information about who fixed an issue, the background around the issue, the original technical description, and other key information.

This can be very helpful when account managers or support personnel need to know who to ask about an issue if a customer raises a related question. It also allows special versions to be delivered to partners that may include specific issues that relate to the integrations they're concerned with. Furthermore, it provides a valuable resource when doing quality assurance, since the release notes can easily be used to double-check features and fixes.

These abilities all stem from creating well-designed, structured DITA content, and they're extremely valuable. Since it's DITA content, we can deliver release notes in multiple formats based on user preference, and we can make them easily searchable, too. Personalization for everybody!

Suggested reading

No items found.

Create great content together

Write, review, translate, and publish all from one system. Heretto is the only ContentOps platform that allows multiple authors to work together at the same time.