Crafting Valuable Release Notes

Release notes enable product managers to broadcast information to users, outside of the confines of the product’s innate user experience flows. That makes release notes particularly invaluable for product managers, especially for those who seek adoption of their product.

10 months ago   •   9 min read

Team Producter
Crafting Valuable Release Notes

Release notes enable product managers to broadcast information to users, outside of the confines of the product’s innate user experience flows. That makes release notes particularly invaluable for product managers, especially for those who seek adoption of their product.

In my experience as a product management coach and instructor, I’ve found that the humble act of writing release notes is overlooked and underutilized. That’s why I’ve pulled together this guide for writing valuable release notes.

First, we’ll discuss how exactly release notes provide value. Then, we’ll discuss the intended audience for release notes, as well as what their pain points are. Afterwards, we’ll break down how to write release notes that provide real value, and we’ll close with a discussion on how to continually improve release notes over time.

Let’s dive in!

How can release notes provide value?

Release Notes
Release Notes

First, release notes inform users about how the product works. By doing so, product managers increase the chances that their product is being used in the way that it was designed. This is particularly important for highly-complex products, such as those that have branching workflows or lots of configurable options.

Second, release notes demonstrate progress over time. When users and customers see regular release notes, they feel reassured that the product team is continually investing in the product. After all, you wouldn’t want to use a product where you stopped getting updates and releases!

Third, release notes help users feel heard. As a user, I love it when release notes highlight that a particular feature was released due to specific user feedback. Even if it wasn’t my user feedback that was addressed, I’ll feel seen, heard, understood, and valued. People have an emotional attachment to their favorite products, so it’s important to close the loop and let users know that we’re listening and taking action on their feedback.

Fourth, release notes enable product teams to call out any upcoming changes, such as refactors or feature deprecations. Of course, while product teams should be using other avenues like newsletters or customer quarterly business reviews for critical topics like these, it’s still helpful to let users know about what’s coming down the road.

Fifth, release notes help set expectations around future velocity. For example, if there’s a highly-anticipated feature that’s on the docket but customers aren’t sure when it’s coming, product teams can provide a quick status update on their progress. By doing so, customers can then reset their expectations and plan accordingly.

Let’s now discuss who our intended audience is for our release notes. In other words, who is reading our release notes? By understanding who’s reading, we can then make sure to write for that audience and solve their pains.

Who is the audience for release notes?

The first audience that comes to mind is our customers. Our customers are typically quite interested in receiving and digesting release notes, because release notes enable them to better understand how to use the product to improve their processes — whether those processes are part of their personal lives, or whether those are part of their businesses.

Our most dedicated customers have molded a part of their lives around our products, so it’s painful to them when the product changes and they’re not aware of it! By staying on top of release notes, customers ensure that they’re not taken by surprise.

Therefore, our release notes need to be comprehensive: they need to cover the full set of changes that we’re making, ranging from new functionality to deprecation of old functionality, and ranging from UX layouts to copy changes.

But, there’s a crucial distinction we need to make here. Customers and end-users are not always one and the same, especially for B2B (business to business products)!

To clarify, customers are the people who pay for the product, and end-users are the ones who actually use it on a day-to-day basis. As an example, the finance team may purchase licenses for an HR product like Gusto or ADP, but the HR team is the one who actually uses it every day.

Therefore, it’s important to remember that end-users also benefit from reading our release notes. As noted above, end-users and customers may not belong to the same department.

A frequent pain that enterprise end-users run into is that they’re not informed when the product changes, because product release notes wind up only going to specific customer contacts. That’s why it’s valuable to have a way to access release notes from within the product itself, rather than keeping it completely divorced from the product.

By giving end-users access to release notes, we can also ensure that the people who are actually using our product are aware of what’s changed, and why it’s changed. That way, our end-users know that we’re keeping their needs front and center as we craft new functionality.

But, it’s not just customers and end-users who benefit from release notes. Our own internal departments also benefit greatly from release notes!

Specifically, our customer-facing teams (e.g. customer support teams, customer success teams, account management teams, deployment teams, sales teams, etc.) all benefit from release notes too.

When customer-facing teams don’t know what’s changed in the product, they lose credibility in front of their customers. It’s crucial that we arm our cross-functional partners with knowledge so that they can position themselves as experts of the product. After all, we want our customers to trust their counterparts and to come to them with questions and feedback!

Furthermore, our sister product teams also benefit from centralized release notes. Especially for very large product organizations, it’s not feasible for each individual product manager to personally contact every other teammate about upcoming changes.

When sister product teams aren’t informed about upcoming changes, it causes problems for them. They may wind up building conflicting functionality, or they may wind up duplicating work.

At the end of the day, customers seek a single, unified product, so it’s crucial that we don’t “ship our org charts” and cause information silos between teams.

Since we’ll already be crafting release notes for an external audience, we can also leverage them as a valuable reference for sister product teams to better understand how the product is changing and evolving. By providing the rationale for our changes, as well as clear screenshots or animations of what we’ve changed, we can keep our sister product teams up to speed.

So, now we know who we’re serving whenever we craft release notes. Let’s discuss how to actually write release notes.

How to craft valuable release notes

The key to writing valuable release notes is to focus on the end-users, rather than to claim credit or to congratulate ourselves. While it’s good to celebrate progress, it’s even more important to position our end-users to “become superheroes by using our product.”

Too frequently, I see release notes that are so vague that they lack any concrete information. For example, “improved performance and fixed bugs” is far too generic to offer any meaningful value, because it doesn’t state what kinds of improvements to expect or what kinds of bugs were fixed.

I also see release notes that are written more like sales pitches or marketing press releases than truly actionable release notes. Our release notes are not meant to convince customers to buy our products. Rather, release notes are meant to educate our customers so that they’re set up for success through our products.

To write valuable release notes, each of our release notes should answer these questions:

  • How will this change benefit the end-user?
  • What are the challenges that they might run into when using it?
  • How should they set themselves up to use it best?
  • Who should they contact if they get stuck or need help?

Keep it short and sweet, and try to avoid technical jargon where possible.

As an example, it’s not helpful to discuss a refactored database architecture with day-to-day end-users, but it’s helpful to let them know that we’ve improved search results to come back within 1 second instead of 10 seconds.

Don’t forget that a picture is worth a thousand words, and that a video is worth a dozen pictures!

Where possible, try to provide screenshots or animations so that users have a clearer understanding of what exactly we’re referring to in our notes, and how exactly to use our functionality most effectively.

Now we know how to craft valuable release notes. But, whose responsibility is it to write them?

Who’s in charge of driving the release notes process?

At smaller organizations (up to about 6 product managers total), the product managers themselves should be in charge of writing release notes.

They have a deep awareness of the product, and therefore they’re best positioned to speak to its value proposition and caveats. Since the organization is small, they have strong interactions with cross-functional partners and have intimate knowledge about their customers.

At larger organizations with more than 6 product managers, the product operations team should be leading the effort around writing release notes.

Of course, product managers still need to provide the actual content, but product operations can orchestrate many of the other moving parts.

For example, product ops can orchestrate reviewing the notes with legal & compliance teams, sending the notes to customers, and collating feedback from customers about the notes.

But, release notes isn’t just something that a single team unilaterally writes and sends out.

Other stakeholders should be reviewing release notes too, to maximize the positive impact that you’ll reap as an organization.

Who needs to review release notes?

To drive the largest impact possible, and to ensure that we have alignment across teams, we should review our release notes with internal stakeholders before sending them to customers.

First, we should run our release notes by our legal & compliance teams to keep our bases covered. We don’t want to accidentally say the wrong thing or set the wrong expectations with customers.

Second, we should preview the release notes to someone in support and someone in customer success, at least 1 day before releasing. By doing so, we give them the opportunity to raise any flags and catch any issues. I’ve been able to reposition my release notes more effectively based on the feedback that comes from support and from customer success!

For both of these processes, we should designate the roles beforehand and provide clarity on our expected release notes cadence. That way, our reviewers aren’t caught off guard with unexpected work or unreasonable deadlines.

Whew! We’ve now covered the fundamentals of release notes. But, how can we improve this process over time?

How to improve release notes

Think of release notes as an extended part of the product, similar to how roadmaps and FAQs are an extended part of the product.

Helpful release notes make the product feel more valuable to customers, whereas poorly-written release notes reflect poorly on the product and damage the company’s brand.

Problematically, many teams fail to do customer discovery and research for release notes.

They haven’t found the answers to key questions like “what information do our customers care about?”, “what information do customers wish we provided?”, and “what information is irrelevant to our customers?”

To help make release notes more valuable, it’s worth considering spinning up a “release notes club” with customers. This ongoing customer council can help us answer the questions above in terms of what customers need, and how we can best meet those needs.

In essence, each time you send out your release notes, you give this release notes club the opportunity to weigh in with their feedback on what they found valuable and what they wish you had done differently. This direct line of communication increases trust over time while also providing you with helpful information.

When deciding who should be a part of your release notes club, consider the following factors:

  • Which customers are most valuable to us?
  • Which customers are most loyal to us?
  • Which customers are most likely to give us actionable feedback?

By selecting a mix of customers across these factors, you’ll gather impactful feedback over time that you can use to strengthen your release notes.

On top of that, we want to run internal-facing retrospectives for each release notes cycle. As with any organizational process, we should seek to drive continuous improvement for our release notes process.

Each retrospective should cover the questions:

  • What did we do well this time?
  • What could we have done better this time?
  • What will we do differently next time?

By committing to retrospectives, we can make our release notes more effective over time, while also making the process more efficient for both product managers and other stakeholders.

Closing thoughts

Release notes are underappreciated and should be a core pillar of your product go-to-market tactics.

By investing a bit of time and thought into release notes, you’ll create a significantly stronger body of knowledge around how your product works. From there, you’ll dramatically improve its adoption rate, which eventually leads to more stickiness, more engagement, and more referrals.


Clement Kao is Founder of Product Teacher, a product management education company with the mission of creating accessible and effective resources for a global community of product managers, innovators, founders, and entrepreneurs.

For individuals, Product Teacher offers self-paced courses, career services, and product job openings.

For organizations, Product Teacher offers corporate workshops and consulting services.


Producter is a product management tool designed to become customer-driven.

It helps you create collect feedback, manage tasks, sharing product updates, creating product docs, and tracking roadmap.

👉🏻 Sign up Producter for free

Producter

Spread the word

Keep reading