How to Write Great Product Release Notes — The Ultimate Guide

Summary

• Focus on the value to the customer
• Keep them punchy
• Use plain language
• Include images, videos, gifs, and links to additional information
• Inject your brand’s tone of voice
• Group them logically
• Include specific dates
• Segment them by impacted user
• Provide additional relevant context
• Use release note templates
  

{{resources-component-1}}

Intro

Writing great product release notes is challenging. Even communicating the smallest product change requires careful consideration in terms of when and how it’s communicated to users in your release notes. Without some guidelines in place, you risk confusing or frustrating customers and miss a perfect opportunity to delight users.

In this article, we’re going to look at some of the problems with release notes today, discuss why release notes are a vital component of every software app, and provide some tips for writing great, effective release notes that your customers will love.

The state of release notes today

They’re often an afterthought, or forgotten altogether

A surprising number of software teams fail to communicate some, or even all, of their product changes. Dropping the ball like this creates the ultimate subpar customer experience. For anyone who has worked on the frontlines in support, customer success, sales, or account management, you’ve almost certainly heard from frustrated customers asking: “When did X change and why wasn’t I told about it?”.

‍
If your customers are asking these kinds of questions, it’s a strong signal that your team needs to improve how you’re communicating product changes. You not only need to involve the right folks from marketing, customer success, and other customer-facing teams with the help of a release communication strategy, but also ensure that each and every product change is well-documented. In some cases, companies may be required to maintain an up-to-date audit of product changes in order to comply with certifications like GDPR.

An equally large number of teams do publish release notes, but do so as an afterthought. If your release notes are completed as part of a last-minute checklist around release time, they’re likely not written in a clear, concise manner for your users, missing details, or even incomplete. If your release notes feel like a last-minute task, you're simply not putting your customers first.

Instead of rushing, have a plan in place and commit to a process that makes the comms around your software releases more coordinated. Better yet, make release notes part of your software development and release process. Just like unit tests are run on new code… write release notes for all new changes. If you do this, your customers will never be caught off guard.

The right people don’t see them at the right time

Release notes should be timely. Getting the right information to the right people at the right time is critical to delivering a seamless customer experience. Today, too many customers simply aren’t informed of product changes because they don’t know where to find that information. For software teams who are communicating consistently about releases and changes, their approach to distributing that information is often less than ideal.

‍

Perhaps the announcement got buried in a pile of emails, lost in the mix of help documentation, or maybe it was hidden in a blog post. Whatever the case, customers frequently ask “how can I make sure I get updated on future changes?” and that’s a strong signal for software companies to step up their game when it comes to announcing product changes. 

Release notes should be easy to find, up-to-date, and include an option for customers to receive notifications so that power users are looped in the minute you announce something. Release notes should not be a reactive list of changes, but instead a proactive set of comms on what’s changed.

They’re often too technical, boring, and vague

Historically, release notes have a reputation of being boring, stale, and not detailed enough. We’ve all seen release notes that say something like: “General bug fixes” or “Feature improvements”. Not only is that unhelpful information for your users, but it also opens the door to questions like: “Which bugs?”, “Was the bug I reported fixed?”, “Which features did you improve?”, and “How were they improved?”. If you’ve done the work of fixing bugs and/or enhancing your product in some way, tell your customers in detail how you’ve improved the experience for them! It’s the final step, and arguably the most important.

‍
Relatedly, release notes should be written in plain language that can be understood by a broad audience. Keep in mind that you’re communicating with other humans. Format your release notes in a way that they’re easy to read and comprehend. See this process as an opportunity to communicate additional value directly to your customers. The use of too much technical jargon is doing them a disservice. A simple smell test is asking yourself: “Are these release notes something that I would read and be engaged with if they were sent to me?”.

Why release notes are important

They set expectations with customers

Unless you’re showing up at their office with a box full of swag, customers typically don’t like surprises. A huge part of delivering a great customer experience is setting expectations. It takes a thoughtful combination of people and tools to get this right, and one of these tools is a great release notes process. 

With a single source of truth for product changes, your customers are always on the same page and no one is out of the loop on what has changed, when, and why.

They help close the loop with customers

Release notes are a great way to close the loop with customers about bugs they’ve encountered and features they’ve asked for. We’ve all submitted a feature request to a software vendor, only to never hear anything about the request ever again. Imagine logging a feature request and then seeing it in the release notes a month or two later. As they say, actions speak louder than words.

Not only does this show that the company is genuinely listening to you and ingesting your feedback, but that they care about closing the feedback loop with their users. Release notes are the tool for doing this. Good release notes get your users excited about new functionality, improvements, and bug fixes, while showing your customers how much you value your relationship with them and their patronage of your product or service.

They give customers a single source of truth for product changes

It’s a noisy world out there. We’re all inundated with notifications from Slack, email, social media, to-do lists, and more. A dedicated release notes feed cuts through the noise and gives your customers a single source of truth when they need or want to know what has changed, when, and why.

They’re an effective one-to-many communication tool

Unless your customers have a high touch relationship with a Customer Success Manager or Account Manager, they’re probably not getting regular updates on your roadmap or what’s been shipped in the product. High touch customers get the luxury of quarterly business reviews and other engagements- but what about the rest of your customers?

Release notes are a great way to inform all of your customers what’s changed in your product. This is especially valuable as your company scales to a size where the majority of customers probably won’t have that 1:1 relationship.

They showcase development momentum

Customers frequently ask, “What have you all been working on lately?”. They’ve invested in your product or service and want to see that you’re growing with them. By not communicating clearly about what’s shipped, they may think you haven’t shipped anything. Use your release notes to help answer customer questions and give them an easy way to know what’s happening in the product.

Good release notes show customers you’re keeping busy, improving things, and introducing new features.

A guide for writing great product release notes

Release notes should be about the customer, not about your product or company. Clearly explain how they benefit from the update you shipped. Tip: use “you” instead of “we”.

This isn’t the time or place for long-form marketing language. Keep your release notes concise and to the point so they’re easier to consume. Explain the change efficiently and clearly, and link to places with additional information if the change is large or complex enough to warrant it.

Avoid technical jargon whenever possible. Be specific and make them accessible to a broad audience. Be conscious of geographical locations and languages. Some vocabulary may not resonate well with certain customers.

Here's a (non-comprehensive) list of terms that will likely confuse the average B2B user and that you're better off avoiding if possible:

• front end
• back end
• specific languages (Java, Scala etc.)
• build
• deprecation
• GET
• POST
• PUT
• CRUD
• framework (or any specific framework name)
• library
• major/minor version
• patch
• log(s)
• CI test(s)
• specs
• master
• dev
• staging
• test job(s)

Release notes should be a brief summary of the change. When necessary, link to additional details. If an image or video will help explain a change, include them in the release notes or link to an additional piece of content such as an article in your help center.

Don’t be afraid to lean in to your brand’s tone of voice. But balance this with keeping things easy to understand and not too cheeky. Remember, you’re communicating with a broad audience, but there’s room for your brand to shine in your release notes.

Don’t make your users sift through huge blocks of text. Format your release notes by grouping them into sections like ‘New Features’, ‘Improvements’, ‘Bug Fixes’, etc. That way the reader can quickly focus on the areas that interest them the most.

Imagine seeing a release note about a new feature you’re really excited about… only to find out your plan doesn’t include said feature. Be clear in your release notes which plans and play types may be impacted by a particular change or improvement. At the very least, if it’s not something that customers have access to right then, they should know how to upgrade and gain access to it immediately if they so choose.

Communicating about a change is great, but letting your users know when the thing changed gives them necessary context and leaves less room for questions like: “which day did this bug fix actually roll out?”.

Of course, it’s not always possible to include dates on every single item, but always include the date your release notes were published. Your team will thank you for this as well, as they’ll likely use the release notes for their own benefit.

Anticipate what your customers might be thinking to ask you next. If you changed something, explain how it was before the change. If you released a new feature, walk through how to access and enable the feature. If you fixed a bug, ensure you include which version(s) the bug impacted. Don’t leave your users hanging or force them to contact support to answer these types of questions.

Templates are the perfect way to streamline your release process, save you time, and ensure your release notes are consistent and thorough. And they don't have to be lengthy. In fact, the most commonly used template just answers five key questions:

• What's changed?
• When did it change?
• What's important or valuable about this change?
• What do I need to do? (optional)
• How do I learn more or get help?

For further reading on how to leverage release note templates, including an entire catalog of free templates that you can easily copy and paste, visit our release note templates blog.

Conclusion

If you’re just getting started with release notes, you’re on the right path and you’re well ahead of a lot of software companies.

Remember, a release communication strategy is all about your customers. Release notes are an investment in time and resources, but they shouldn’t be forgotten about or deprioritized. If you truly put your customers first, you’ll make release notes a normal part of your product development process, and your customers will thank you for it.