Release notes are a great way to teach your users about your product.
A document detailing all the newest features, bug fixes, and changes—in short, a list of software updates—release notes are highly informative literature.
With well-written release notes, you can prove you care about your product, increase user engagement, and even support your Sales and Marketing efforts.
However, your users need to read those documents to achieve all of these benefits. Unfortunately, release notes are often shunned by customers.
In this article, we’ll discuss why and teach you how to change the minds of readers who usually don’t read release notes.
Your Release Notes Are Difficult to Find
For users to read your release notes, they first need to be able to find them.
If these documents are accessible from only one website page or stored in locations that aren’t intuitive (e.g., the About page), your users won’t notice them—and you want them to.
Release notes detail your software’s new features, so reading them enables users to derive more value from your product. That’s why it’s important to guide your users to them.
Amoeboidssummarized the concept well:
One strategy for effective feature marketing is advertising your release notes. To do this, try notifying users whenever you publish new release notes and include a direct link.
That way, they can easily find the new document.
Here are some channels to use:
Release notes can easily be repurposed as a blog post, so it’s a good idea to showcase the newest product features in your company’s blog.
Alternatively, you can email users whenever a new release note is published—they’ll definitely notice a new message in their inbox.
In-app notifications are also helpful. A simple, 3-day pop-up box is enough to guide users to the new document.
Finally, if you have a large social media following, tell your followers about the new release notes on your profiles.
The advantage of these options is that they allow hyperlinks, which lead users directly to the document, so they don’t waste time searching for it.
As to the actual location of your release notes, they’re often grouped with roadmaps. The former documents the software’s history, whereas the latter anticipates its future.
Therefore, it makes sense to combine the two—the features described in the release notes probably used to be on the roadmap.
For example, Screenful takes this approach:
Their release notes are right next to their roadmap. This setup presents a general overview of the company’s progress, both recent and upcoming.
Another common release notes location is your company’s knowledge base. Knowledge bases communicate product information, as do release notes, so the two are a perfect fit.
Here are ChartHops’s release notes, located in their knowledge base:
This entire documentation structure—product documentation and release notes—was built with the documentation platform tool Archbee.
The tool can attach the release notes to your product documentation as a knowledge base component.
Archbee is well-optimized for all these use cases, so the setup is straightforward, enabling your users to quickly find the release notes.
Your Release Notes Are Too Vague
The aim of the release notes is to summarize your software’s updates and let everyone know the new, exciting functionalities that have improved the product.
However, to achieve this, your release notes must be clearly written. If they’re too vague, readers won’t understand the upgrades and might bypass new features.
For example, look at this recent release note:
Although it’s humorous, there isn’t much substance to it. Readers don’t learn anything new except that Slack has fixed some bugs.
However, we’re not told where these bugs were, how many were fixed, or why they were fixed. There’s no concrete information helpful to Slack’s users.
Now, compare that snippet with Jira’s bug fixes release notes:
Although slightly technical, Jira is commonly used by developers, so the jargon isn’t out of place.
Considering Jira’s standard audience, it’s preferred, as developers need considerable data to understand updates fully.
These bug fixes are extensive, with countless specifics included. Upon clicking on an issue, you’re presented with screenshots, environment details, steps to reproduce, etc.
Frequent Jira users will greatly appreciate this comprehensive list, as they’ll know immediately if any of their outstanding problems have been solved.
For a non-technical audience, environment details aren’t as important. Instead, media such as photos and videos are an excellent way to ensure that your release notes are clear.
This is an approach utilized by Trello, as you can see in this release note excerpt:
Trello has included a video to help explain the new available Unsplash background images, and anyone who watches it will immediately understand how the new feature functions.
In fact, they probably won’t even have to read the rest of the article. The video is clear enough to communicate everything users need to know.
If you don’t have videos on hand, another strategy to avoid vague release notes is to bolster them with links.
No one wants to read lengthy release notes, but some might require additional explanation. To keep them short yet informative, utilize links.
InVision did this when explaining their scrolling overlays:
Some new users might still need to learn what an overlay is, let alone a scrolling overlay.
However, InVision has included a helpful link to explain the term, so everyone can quickly bring themselves up to speed.
With this tactic, you can easily create clear, digestible reading notes everyone can utilize.
Your Release Notes Are Too Technical
Although vague release notes aren’t helpful, you must ensure you don’t go too far in the other direction and make them too technical.
Anybody, not just developers, might want to read release notes, and it’s likely a lot of non-technical users will be accessing them.
For example, here’s a recent Google release note:
This text is full of technical jargon, mentioning terms such as Query API, integer type fields, Faceting support, etc.
Many potential readers in a non-technical role would need help understanding the new adjustments, as the language is simply too niche.
And considering how widely adopted Google Workspace is, many users would likely require clarification.
As such, it’s preferable to write accessible, legible release notes that anyone from any profession can read and easily understand.
That way, all users can get maximum value out of your product.
John C. Friedly, a senior lecturer at MIT, has also highlighted this:
At the end of the day, you’re not writing release notes for yourself. You already know everything about your software.
The release notes are intended exclusively for users, so you should always focus on them when writing these documents.
If you have a highly technical product and are unsure how to write plainer release notes, try applying the following constructions:
These statements are all straightforward and clear-cut. They don’t leave any room for confusion, and their structure is easy to follow.
If you have any complex, lengthy updates to communicate, try sticking to these templates as much as possible.
It’s preferable to write in brief, choppy sentences and clearly explain yourself than sacrifice readability for stylistics. Ultimately, the goal is for the release notes to be easily understood.
To see this strategy in action, take a look at Intercom’s release notes:
Intercom immediately states what the new feature is. They then explain what can be done with it and highlight how this wasn’t possible previously.
Finally, it’s explained why this customization is helpful for your business. The clear presentation ensures users—all users—will immediately understand the benefits of the new feature.
Furthermore, the entire tone of the message is colloquial and inviting. Although the content is professional, the emojis and the informal vocabulary help attract the reader.
Intercom’s release note style is never a bad choice. The simple vocabulary and the warm tone aren’t technical in the slightest, accessible to everyone, yet still highly informative.
Your Release Notes Are Too Long
Your users are busy people. They have meetings to attend, projects to work on, and deadlines to meet.
They might enjoy your product, but that doesn’t necessarily mean they want to read about it for the entire day.
Ideally, your release notes should be long enough to convey helpful information, yet short enough for users to want to read them and be able to do so quickly.
Long release notes can be tiring, especially if they turn out to be unimportant for how your reader uses your software.
For example, look at MySQL’s release notes:
These release notes are aimed at developers, so the technical language isn’t an issue. However, the formatting and length are.
When faced with this wall of text, most users will immediately feel overwhelmed.
The never-ending, blocky passage is a poor layout that instantly creates mental strain—especially because it is so long.
If this text were shorter or at least broken up into smaller blocks, it would be easier to digest.
Now compare that release note with the following:
That’s the entire article. Short, simple, and straight to the point, Amazon Business has utilized a third of the space as MySQL, yet managed to effectively and clearly explain their new feature.
For today’s busy professionals, this bite-sized format is perfect, as they won’t lose time dissecting the information pertinent to them.
Instead, the entire text is easily scannable and can be read in less than five minutes.
However, if your newest release notes are quite extensive, and five minutes isn’t enough to go through them, try breaking up the information into thematic groupings.
Here’s an example:
Although Mozilla had a lot to say there, they segmented their announcements into different categories.
This automatically shortens the text as updates are delegated to their corresponding sections, thus avoiding creating a wall of text.
With the content divided into thematic chunks, it’s much easier for users to immediately pinpoint the sections that interest them.
Another tactic for shortening long texts is utilizing bullet points. They automatically cut down word count and effectively break the content into short chunks.
The personal task management software Things took this approach:
Although not as short as the others, the text is nonetheless segmented and, therefore, easier to digest.
Each update is only a sentence long, meaning users can skim through all the updates quickly.
Your Release Notes Are Not Organized
We previously mentioned how grouping information into thematic categories makes reading release notes easier, as they shorten the text.
However, this tactic is also helpful for another important reason—they help organize the text.
No one wants to open your release notes and face uniform, unformatted paragraphs. To understand why, look at the image below:
There is nothing to distinguish any parts of this text from the whole. Readers can’t know which parts are important, nor what section addresses bug fixes, new features, etc.
To discover this information, users must read the entire document, as there aren’t any signposts to help zero in on specific material. These release notes are hard to navigate.
However, you can avoid this predicament by introducing a simple structure, such as the following:
The header, located at the top, should specify the release version and the date of release.
Afterward comes an overview of any new features included in the release.
Next is an issue summary, which is essentially an informative list of bug fixes.
The resolution details any changes or enhancements made to accommodate feedback requests.
Finally, some release notes end with impacts, which describe necessary changes in hardware or configuration to install the new release.
This layout is popular among several companies. For example, Twitter uses a variation:
This document is grouped very similarly to the aforementioned structure—the only section missing is Impacts.
Otherwise, the header, overview, issue summary, and resolutions are all present, and readers can easily navigate to whatever section is most relevant to them.
Furthermore, Twitter also signposts each bullet point with bolded text to indicate what each point references.
That way, readers can immediately locate segments that interest them and skip over any irrelevant information.
However, this structure is most commonly used when communicating several updates at once.
If you want to convey only one significant update, there are other, more user-centric organizational methods.
For example, look at how HubSpot announced a new feature:
This release note is designed to answer possible questions users might ask.
Readers can immediately jump to the three most important points of any new feature: what it is, why it’s important, and how it works.
By implementing this layout, you ensure your document focuses on the user while maintaining a clear-cut, logical organization.
Conclusion
Release notes are a great resource. They can promote product adoption, increase user engagement, and, most importantly, educate your customer base.
However, you first need to ensure your users are actually reading your release notes.
For starters, place the documents in a logical location that is easy to find.
Regarding the text’s language, it shouldn’t be too technical as to alienate non-technical users, but it shouldn’t be too vague either.
Finally, try to keep the release notes short and well-organized, as this increases readability.
Follow these tips, and you’ll be able to create well-written, engaging release notes your users will love to read.
