When you start thinking about software release notes, the first thing that likely comes to your mind is that they are boring. Traditionally, most software release notes are associated with technical explanations which are very detailed and tend to be uninteresting for most average people.

Nowadays, release notes have become something equivalent to Terms & Conditions statements that almost no one ever read. They are usually written very poorly with little to no regard and thought that actual human beings are reading them.

However, some people do read release notes which means that they can be a great opportunity to communicate with your customer base. Unfortunately, not all companies are aware of this opportunity, including most (or even all) of your competitors.


Why should you write release notes?

Like we already mentioned, release notes are an additional opportunity to connect with your customers. To build meaningful relationships with them, you need to do way more than answering their questions or replying to their social media comments. You also need to stay in contact with them.

Release notes are a great opportunity to let your customers know that you've heard them, that you find their opinions and feedback valuable and then you'll be delivering functionalities based on their feedback and what you learned from them. By doing this frequently enough, you are able to keep the conversation and connection with your customers more active while at the same time making your customers feel like they are part of the product development process.

Why aren’t people reading release notes?

Before taking a look at some release notes best practices, we need to review the usual practice of writing release notes and try to figure out the exact reasons why most people aren’t reading them.

Most release notes have the tendency to be too vague

One of the most common problems with release notes is that they actually don't tell us, the readers, much. Most commonly, release notes consist out of the following: “The latest version contains bug fixes and performance improvements”.

This doesn’t say anything! We all pretty much know that the update is either going to fix a problem, add a new feature, improve an aspect of the app or any combination of the three. That’s what are they for. Companies like Facebook, Microsoft, and Acrobat tend to publish these kinds of release notes.

Most release notes are written in technical language

While release notes typically describe technical updates to the product, this doesn't mean that they need to be writing in dev-speak. "App notification ticket #1649 issue resolved" doesn't mean anything to anyone other than those familiar with the specific ticket, which is a rather short list of people. However, most companies today are still publishing updates that include this type of useless release notes.

Release notes that go on for too long

You have seen these types of release notes plenty of times. These release notes tend to go on and on to that point that it feels like you'll never reach the end of the page. Some software companies basically cramp together a bunch of words into a huge block of text in a way that you'll have no idea where a specific note ends and the next one beggings.

It looks like these companies have just scribbled out a bunch of meaningless words just for the sake of it. While we know that people are busy, that things get tough, and that product managers have a lot on their plates, especially when the release date is closing in, bad release notes are a missed opportunity to connect with your customers.

While it's still true that most people will never read a single release note you or anyone else includes with a new update, that doesn't mean that you shouldn't make them interesting and fun for those that actually end up reading them? They are still your customers.

Now that we know why you should write release notes as well as why people aren’t reading them, let’s take a look at what to include in the and some of the release notes best practices.

9 Release Notes Best Practices

While there isn't a universal way to write software release notes, there are still general best practices you should follow.

1. Start with what most important for the customers

Most customers are interested in what the new version of the product does for them. This means that they don't necessarily care about the update itself. You'll need to grab their attention when introducing new features in release notes. The easiest way to do that is to start the release notes by showing the update's core value for the customer.

Once you've told them exactly what benefits are they getting, you can start talking about the details of how the features work.

2. Figure out how frequently you want to publish release notes

You first need to choose whether you want to include release notes only when you have a notable release or do you want to publish release notes on a predetermined schedule. If you go with the latter option, you need to make sure that you are focusing on all new features and fixes, not just the most important ones, as you'll only publish release notes occasionally.


3. Pick the appropriate length of your release notes

The length of your release notes may depend on how frequently you publish them. Bear in mind that good and quality release notes take time so be sure you can allocate it. Publishing a set of bullet points once a week could potentially serve your needs.

4. Version your release notes

The first thing you'll need to do is include some kind of timestamp or versioning for what you're releasing. The most common way to title release notes is either by the product's version name (i.e., 2.3.5) or by the month in which that version of the product was released.


5. Use appropriate language in your release notes

Always remember you're talking directly to your customers so you don't need to include any marketing jargon. Try to keep the words as simple as possible. Write your release notes as you would explain them to someone that isn't a tech person.


However, this doesn’t apply if you are releasing a highly technical update. Regardless, always remember that you are talking to YOUR customers and adjust the language accordingly.

6. Group your release notes

If a giant block of text is what your customers see when opening your release notes, they probably aren't going to read it. This is why you need to make sure that your notes are grouped in a logical way and that the sections are divided with visible headings. This helps your customers focus on what they actually want to read.


7. When possible, include videos, GIFS, and other visual cues

For new product updates, the most common practice is to include details when describing them. Videos and GIFs are also excellent and can sometimes do all the talking, meaning you won't need to explain anything.


In addition to the visual elements, your release notes should include more info about each of the features mentioned. Whether it's a user guide, a video tutorial, or anything else, make sure you include it for those people looking to get more info.


9. Make sure your users can see your release notes

While many people think that email is the most relevant channel to update users, it's far from the truth as email open rates are almost always very low and don't get enough engagement you are most likely expecting. If possible, make an update announcement right within your product. By doing this, your customers are able to try out the new features right away and in the context of the app. This increases engagement with new features.


Wrapping things up

The reason why release notes are left unread is that most of them tend to be too vague, full of technical language and are simply too long. However, that doesn't mean that you shouldn't pay attention to them.  Release notes provide a unique opportunity to connect with your customers and ensure they know you're listening to them and their needs and that you’ll consider their feedback.

The release notes best practices say that the first thing you should do is to start with what's most important to the customer. Next, you need to figure out how frequently you want to publish release notes. You also need to write them in an appropriate length, version them properly, use language that makes sense both to the audience and the product update itself.

Great release notes are grouped logically, they include GIFs, videos, relevant links to more information and are published in a way that most customers can see them.

If you follow these release notes best practices you can be sure that the features you mention in them will be better adopted by your users.