How to Write Great Product Release Notes

Product release notes are an invaluable component of your software service.

These documents essentially record all of the updates to your software, detailing bug fixes, new features, and general product changes.

With such documentation, you can kill several birds with one stone. You can educate users on new features, promote your product, and assist your salespeople’s efforts.

However, the only way to achieve this is to ensure that the release notes are well-written. Otherwise, all the benefits automatically go down the drain.

That’s what this article is for—we’re here to teach you how to write great product release notes.

Be Precise in Your Descriptions

Release notes usually serve as a record of all software updates, be it new features, bug fixes, or alterations to existing functionalities.

All three possibilities can significantly affect your customers and improve their user experience.

As such, your release notes should be precisely and clearly written. That way, users will know exactly what value they can expect from the new release.

If the release notes are too vague, the opposite happens—users can’t utilize the new improvements in a way that suits them.

Sarah Perez described the downsides of vague release notes well:

This inattention to detail is a disservice to users, who no longer have the benefit of understanding what the updated app will now do — or not do — as the case may be […] They don’t know what functionality has changed or how the user experience is being affected.

When release notes are unclear, users often won’t even understand how the software has changed. In such cases, they may as well not have read the document.

Such precise descriptions are especially important for developer-centric release notes.

Software is complex, and release notes should be exact and meticulous for developers to keep up with their tools and applications.

Consider the API release notes for Google Maps:

Each bullet point is chock-full of explicit technical information developers will need to use the resource effectively.

There’s no ambiguity, and no filler text, so developers can quickly scan the document and discover precisely what they need.

However, you should also exercise this precision in more general, non-technical release notes.

Just because you’re writing for all your users, and not exclusively developers, it doesn’t mean you should be inattentive.

For example, look at Wrike’s release notes:

Each bug fix is described in detail, with plenty of information about what wasn’t functioning.

If anyone was avoiding these functionalities because of a specific bug, they now know they can start using them again.

In other words, users easily understand exactly what steps Wrike has taken to improve their user experience and how this resolution will assist them.

Another precision tactic is to employ identifying tags for each release note. For example, you could use blog, integrations, security, etc.

This is especially useful if you have different products, as you can easily specify which release notes are for which products.

HubSpot took this approach, utilizing the following tags:

As you can see, these tags are used to signpost which new features can be used in which product. There is even an all product groups option.

These tags are a fantastic way to add an extra level of precision to your release notes, allowing users to easily understand the impact of each new update.

Write Your Release Notes Using Plan Language

Your release notes will likely be read by users of all professions—Marketing, Sales, HR, etc.

Therefore, although your release notes ought to be precise, it doesn’t mean they have to be so technical that the readers can’t understand them.

For example, imagine if your random number generator started running faster because you switched the entropy extractor from SHA1 to BLAKE2s.

Your readers don’t need to know that level of detail. The developers might be interested, but most users won’t understand the technical jargon.

Their only concern is that the feature is faster, never mind how. In other words, plain language is often the trick to a successful release note.

Aside from entropy extractors, here’s some more vocabulary that’s best avoided if the release notes are not meant to be read only by IT professionals:

It’s unlikely that anyone outside of Development will understand any of the above terms, especially concerning specific languages and frameworks.

When compiling your release notes, ensure you steer clear of these words.

Instead, try to structure your language in a way that addresses your users’ issues.

Explain your updates so that the users understand how the change will affect them, what benefits they’ll enjoy, and how it will solve their problems.

Ideally, these are the questions you want to address in your release notes:

You should focus on answering these questions using plain language. Users want to know how the new release will affect them, not how the backend database structure has changed.

For example, ProductPlan replied to some of the above questions in this release note:

ProductPlan has explained its new features in clear-cut, straightforward language that anyone, even non-users can understand.

Furthermore, ProductPlan also spells out the benefits these new functions bring. The first feature reduces time and clicks, whereas the second helps identify points of contact.

This type of information is what interests your readers—not the technical specifications themselves.

Users want to read simple, forthright descriptions of how their user experience will improve.

Another company that does a fantastic job of presenting release notes clearly is Todoist. Look at one of their release notes:

The tone of the note is warm, inviting, and highly colloquial. Despite the professional content, Todoist composes its release notes as if talking to an old friend.

There’s even a humorous undertone to try and make you laugh and an emoji to drive the point home.

Such writing might not be typical corporate language, but that’s irrelevant in a release note context. All that matters is that everyone clearly understands the content.

Keep Your Release Notes Short

Information is best consumed in small bursts. Although your new release probably has many impressive functionalities, your users don’t necessarily want to hear every little detail.

Let’s say you’re introducing several new integrations. Your users will be interested in the exact tools, but likely won’t care about each new automatic workflow.

That level of detail will just overwhelm them.

In other words, keep your release notes short and sweet, as concise release notes are the most approachable.

An easy method of keeping your release notes short is to include hyperlinks.

That way, interested users have easy access to in-depth information, yet the uninterested ones aren’t burdened with irrelevant reading.

For example, look at Percy’s release notes:

Each release note is no longer than two sentences, yet it’s entirely clear what the update is about. If it’s irrelevant to your users, they can skip the release note.

However, if they’re interested, there’s a helpful link containing further information.

It’s a good idea for the link to lead readers to a knowledge base where it’s easiest to present extensive product intelligence. Archbee took this approach:

Each of these links redirects to Archbee’s documentation, which explains the feature in detail. For example:

You can see here how including links in your release notes, instead of repeating detailed explanations, can dramatically facilitate documentation writing and management, making it a superb method for organizing your product resources.

With an elegant knowledge base, your release notes will never be too long. All the information can be thoroughly explained in the knowledge base.

If your knowledge base isn’t yet fully updated, another method to shorten the document is employing bullet points.

These automatically reduce the word count by dividing the text into small chunks.

Here’s an example:

Although there’s plenty of data, it’s easily digestible because each point is concisely summarized and segmented into bullet points. Readers can scan the document quickly.

If you’re unsure if your update is short enough, try communicating it via Twitter. If the announcement fits Twitter’s 280-character limit, it’s short enough.

If not, you might want to compact it further.

For example, Sophos has used Twitter for its release notes:

This release note is clear and informative, yet bite-sized. Despite the limitations of the format, users immediately understand the changes.

Although not all your release notes need to be this short, they should be closer to this example than pages long.

Use Headings to Organize Your Release Notes

No one enjoys reading a wall of text. Such unformatted, uniform text seems never-ending, as there’s no logical point where readers can take a mental rest.

This lack of structural breaks significantly hinders the readers’ focus.

To avoid exhausting your users, it’s worth utilizing headings to organize your release notes.

This format helps break up your content into thematic groups, automatically making the document more readable.

Furthermore, this structure helps readers quickly find the information that concerns them most. Look at how Slack uses headings:

The text is divided into three distinct sections: What’s New, Bug Fixes, and Security Guidance.

Readers will know exactly where to find whatever interests them and can quickly locate their most relevant announcements.

However, there’s an additional tactic that might improve Slack’s layout even more. Take a look at GatherContent’s release notes:

Each heading is color-coded: bugs are purple, updates are gray, and features are green.

This additional visual aid further highlights the differences between sections, and users can immediately spot each segment’s subject matter without even reading the headings.

Such color-coding significantly aids organization, as users can quickly move through the document.

These headings are especially useful when you have longer release notes. Lengthy release notes often also contain a heading titled “Overview” or a table of contents for easier navigation.

UIPath took this approach:

All of the headings are outlined on the right side, so the reader has an overview of the document’s different topics and can easily navigate the text.

Furthermore, these listed headings are also links, so users can immediately jump to the section that interests them.

Such interactive tables of contents are hugely helpful since they prevent endless user scrolling.

These interactive tables are also frequently employed to organize all release notes, not just the content of one document. This is usually done according to the release date, as shown below:

This overview is done chronologically, with the newest document nearest the top.

With this synopsis, users can easily traverse all of InVision’s most recent release notes and examine their latest changes.

This way of organizing release notes is especially beneficial for users who haven’t used your tool for a while, as they can quickly bring themselves up to speed.

All in all, headings are a superb way to organize your release notes and are guaranteed to facilitate document navigation.

Include Visuals for Easier Understanding

The ultimate goal of release notes is to convey your software’s newest updates to your users.

You want readers to understand how your product has improved and what new, exciting functionalities have been introduced.

However, text alone often isn’t the best medium for this.

A more effective approach is incorporating visuals with the text, as media elements are likely to improve your users' understanding of the changes in your software.

Just consider the statistics below:

Visuals often ensure better information retention than simple text. Your readers are more likely to remember your release notes content if they contain images, videos, or GIFs.

For example, Atlassian regularly includes images in their release notes. Take a look:

This is an image of Atlassian’s new collaborative editing feature, enabling users to see the function before trying it out themselves.

As such, they should immediately know how to utilize the function upon first use, having already viewed a preview.

In addition, Atlassian has also annotated the image to draw the reader’s attention to essential aspects. Thanks to this guidance, users will know what to pay attention to during use.

Although these images are helpful, video is perhaps even more impactful. Firstly, it’s a more suitable medium for explaining multi-step features.

Furthermore, Its animation aspect should ensure increased memory retention, as opposed to static images.

Some companies even utilize videos to present their full release notes as an alternative to a written document. GlassHive is a good example:

Source: GlassHive on YouTube

Since a video is more dynamic than a static, immobile document, users have greater chances of remembering all your updates.

It’s well worth trying out the strategy or at least offering a video as an addition to your release note document.

Finally, if you’re compiling developer-centric documentation, it’s always a good idea to include code snippets to explain your content.

Such code excerpts will work as specific guidelines for your technical audience, and you’ll significantly reduce the chances of misunderstanding.

For example, Google Chrome regularly includes code snippets in its release notes:

These images are a great help to developers, providing specific examples of the function in question.

Like most visuals, these media elements will enable quicker understanding and are an excellent method to effectively guide readers through your new feature.

Conclusion

Release notes are a must-have for every software company.

A log of all your software updates, this document can provide user education, promote user engagement, and even assist Sales and Marketing efforts—as long as it’s written well.

To compose high-quality release notes and reap those benefits, ensure your descriptions are precise while still employing plain language.

Also, the ideal release note is short, but if you must write a longer document, organize it with headings.

Finally, do your best to include visuals—this will help users understand the document better.

Follow these tips, and you’ll be composing fantastic release notes your users will surely appreciate.

‍