Select Page

Note: This blog post is an abstract of Part One of Casey Jordan’s two part webinar on the subject of release notes. Webinar recordings for part 1 and 2 can be found here.


Part One: Release Notes Issues and Best Practices

In the presentation we will be covering two important subjects:

1) How to better create high quality and personalized release notes to improve customer satisfaction/confidence and attract new customers

2) Breaking down barriers to managing and creating these 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 can be a great way to increase customer satisfaction and confidence as well as attract new customers. However, most companies treat release notes as an afterthought, something that just has to be done in order for the 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. And worse, they are frequently disconnected from the product documentation, so the reader has no easy way to find the area in the documentation that explains changes in more detail.

A wasted opportunity to increase revenue and 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. However, that has rapidly changed over the last decade as users have become more 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 provides the ability for users to see if a feature they requested or a bug they reported has been given attention in the new version.

And since release notes typically are presented directly to the user when they begin using the product, or when they are asked to upgrade, they can often be the first documentation-related interaction with your software.

This impacts your reputation, for better or worse

Because release notes are the first content related interaction your users have with new product versions, they can leave a lasting impression and 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 will find out what others think. Reputation is crucial, and people are becoming more vocal about their satisfaction, or dissatisfaction with release notes.

A quick Twitter search illustrates this point quite well:

The Good:

The Bad:

Not only are users reading the release notes, but some are invested enough that they feel the need to make a public statement, to their peers, when they like or dislike what they see. Recommendations are one of the most powerful ways to attract new customers or keep existing ones and release notes create an opportunity for a good recommendation (or a bad one).

Defining and achieving high quality when it comes to release notes

In complex environments, the resources required for creating high quality release notes can be a huge burden. Due to this, they are often delivered as quickly as possible with little usefulness. Transforming release notes into a useful resource is the major step towards quality. Just like documentation, release notes have to be informative and help the user to be useful.

With the right process and tools, we can significantly increase the usefulness of release notes and leverage them to create happier customers. We can view this as a “release notes maturity model” with 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”

Curating correctly is an important process since we must ensure that as much of the original meaning/information is preserved while still being understandable to the average user.

Curation can also be taken further, by adding screenshots, video or links to documentation, however, it’s best to use this only when you want to really highlight something special, and 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 note information presented in an easily digestible way. 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:


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:

“Our prospective easyDITA customers read through our docs site and release notes before they buy our software. We know because we track it (another integration activity).”

Level Four: Personalized

With the right process, release notes can also be personalized for a particular product tier, a particular audience or even a particular customer or partner. This level of personalization or ‘conditionalization’ makes it easy for customers to find information they specifically require. This extra attention to details they care about has a direct impact on customer satisfaction and retention.

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

Tip: Providing personalized release notes can be a huge win for customers, especially in the enterprise. The extra attention to their needs has a big impact on retention and satisfaction.

We also use this internally to create versions of release notes with a progressive disclosure of information for internal use, or for 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 useful information. This can be very helpful when account managers or support agents need to know who to ask about an issue if a customer raises a question related to the notes. Also, it allows special versions to be delivered to partners that may include just issues that relate to integrations that they care about. Furthermore, it provides a valuable resource when doing quality assurance, since the release notes can easily be used to double check feature or fixes.

These abilities all stem from creating well designed structured (DITA) content and turn out to be extremely valuable. And since the content is in DITA, we can also deliver the release notes in multiple formats to users based on their desired method of receiving them as well as make them searchable. More personalization!

This is Part One of a two-part series. We are posting Part Two in the near future.

A better way to manage technical documents

Casey Jordan

Casey is a software entrepreneur and an open standards evangelist.

In 2005 Casey co-founded Jorsek LLC, with the goal of improving how the world created and exchanged content. Jorsek developed and brought to market a new component content management system focused around DITA, an open standard for authoring, organizing, and delivering high-value information.

Casey played a key role in developing the business model and architecture for Jorsek's flagship product, an advanced web-based XML content management system called easyDITA.
Get a Demo