Great release notes are a powerful tool for SaaS companies: they can build trust with end users, demonstrate ongoing value, and help with product education. But what separates the good release notes from the average?

I sat down with Outverse co-founder Ollie Steadman, who heads up the Product org at Outverse and has written (and read) many changelogs over the years. Here, he shares his experience of the what, why, and how of excellent release notes.

• What release notes are (and if they differ from changelogs)
• How to write engaging release notes
• How software release notes can help with everything from product education to hiring efforts
• Where to distribute release notes
• Plus: a simple release notes template
• Plus: Release notes examples, from SaaS companies our Product team love

First, though, let's take a quick look at why release notes matter in the first place.

What are product release notes?

Product release notes are a written summary of the changes included in a new version of software. They keep customers up to date and help users understand the changes in a new version by providing them with context for what they'll experience when they next use your product.

"With technical products, your releases might include a meaningful difference in terms of API or SDKs," explains Ollie. "Obviously, you'll have product-level things in place to prevent stuff breaking when a new version is pushed, but maybe customers need to update something on their end. Publish release notes to keep people informed on the changes you've made and how that affects their experience."

Ideally, release notes should be short enough that customers can understand at a glance what's new and why it matters. This isn't a full feature tour — save that for the blog.

Release notes are used in a few places:

1. On the marketing site. Most software companies host their release notes on a dedicated web page. Usually, release notes are displayed in reverse chronological order (newest first) and linked to from somewhere relatively visible — for example, from the website header or footer, or from the knowledge base or support site.
2. On the app store. If a product is available on an app store (mobile or desktop), release notes will appear on the app store listing page.
3. On the company blog. For important features, a blog post showcase is often part of the launch plan. Typically, this post is authored by somebody on the Product team, and provides a tour of the feature, an exploration of why it was created, and relevant information on how to benefit from it. These posts often link through to the release notes page.
4. In the community. Some companies publish their release notes directly into their community forum. This approach invites customer feedback and discussion from the community, and can be a great method for building trust, starting a conversation, and getting customers excited.
5. On social media. Increasingly, social networks are limiting the reach of posts that link out to other sites. For smaller releases, it's not uncommon for software companies to copy their release notes directly to the social network — which saves the reader a click, and increases the post's performance and visibility on the social network. At Outverse, we typically release smaller, focused updates on a biweekly cadence. This makes them ideal for posting directly to social: they're short and sweet, and often have a standout feature that can serve as a visual or video for the post. If you do this, make sure to post to your changelog page too: this should always be your main source of truth for product updates.

How good release notes build trust and demonstrate culture

"One way you can build trust with release notes is by articulating a cadence of shipping," says Ollie. "It's a good way to softly demonstrate a company's culture when it comes to shipping quickly, valuing users, and fixing bugs."

Pick a cadence and try to stick with it, especially if your changelog entries are small. Frequency will be different for every team — it's not how often that matters, but how consistently.

"Say you usually ship every two weeks, and then one month you only ship once. That's fine. But try not to slip a few months in a row. A long time between release notes, or erratic cadence, can look like stagnation to customers," explains Ollie. "Even if actually all that happened is the team had other priorities and didn't write the release notes that week."

Well-written release notes can create an optimism and excitement with both current and potential users: frequent updates that improve the product serve as a reminder that the subscription has value. They can also be a great opportunity to show how you've incorporated user feedback, from fixing bugs to releasing a much-requested feature.

"It's also a good way to keep people checking back in. Even if they haven't yet converted or signed up for the product, you increase the surface area for them to do that," explains Ollie.

Another benefit? Attracting the right type of candidate from a recruitment standpoint.

"One of the first things I do when I come across a new product is check out the changelog," says Ollie. "And I know lots of people who, when looking for a new role — especially on a really product-focused team — will immediately check the release notes for the product to get a sense of the company and its approach to craft."

"The absence of release notes doesn't mean that like a team doesn't ship quickly and isn't an amazing team, but a great changelog is low-hanging fruit in terms of evidencing these things externally."

Changelog vs release notes

The terms changelog and release notes are used somewhat interchangeably these days.

"It's more of a semantic difference at this point," says Ollie. "More technically focused products, like dev tools, will usually call it a changelog."

When people do use the terms differently, they often distinguish them as:

Changelog: A changelog is a list of changes made to the product. It includes new features, bug fixes and other notable updates to the product.  Typically, a changelog is a bit sparser than release notes, and doesn't explain the "so what?" of the update. It states what's new and leaves it up to the user to understand what that means for them.

Release notes: Release notes are written by product, product marketing or development team to highlight what's new in a particular release of their software or app. They typically include information about what's changed since the last version; how it impacts existing users; links to documentation explaining how to use those new features; and contact information. Great release notes are usually written by someone with a deep understanding of significant new features and the product roadmap at large.

The key is to ensure that whoever writes the release notes understands the product, is familiar with the audience, and has excellent communication skills to translate complex concepts into understandable and clear language.

💡 Make sure your team has a shared understanding of what release notes are (or changelogs, if that's the term you prefer). Ultimately, it doesn't matter what you call them, as long as you're agreed on what good looks like.

What to include in your release notes

1. An introduction

To respect your customers' time, start your release notes with a quick summary of what the update contains (e.g., "This release includes two major changes: X and Y"). That way, they don't need to read on if it's not relevant to their use case.

2. An explanation of each new feature

"Focus on things that are going to engage users or potential users. Make sure that any new features or fixes are framed in a way that the user understands the immediate value, and maybe even the longer term vision," says Ollie.

"There's nuance here depending on what the product is, and the inclinations of your users, but broadly speaking, 'we migrated a component from React to Svelte' is not going to be particularly interesting to customers, even if you know it's actually providing value behind the scenes."

Your goal is to help customers understand why they should care about your latest update and how it will benefit them, without overwhelming users with too may technical details — or giving so few that it's unhelpful. Take this example:

👎 Added keyboard shortcuts

👍 Added 12 new keyboard shortcuts to make it quicker and easier to navigate your Outverse workspace. View all shortcuts.

3. A separate section for bug fixes

Separate feature updates from minor improvements (e.g. a fixed bug) so your release notes are easier to skim. Significant or widely reported bugs warrant a longer description, but if you're only including minor fixes that likely won't be noticed by users, you can summarize as "bug fixes and improvements" or similar.

Use visuals in your software release notes

While words are enough to explain most changes, some features will be much more exciting to your customers if you share a visual alongside.

This is a great time to use visuals:

• Screenshots
• Annotated mockups
• Side-by-side comparisons
• Short gifs
• 30-second videos (e.g. Loom, ScreenStudio)

This can also be a good opportunity to provide instructions for how to use these new features in context — for example: "When you click on your profile icon, you'll now see the option to..."

It's worth noting that most app stores won't allow visuals within the release notes themselves, so if you're using visuals, make sure they're complementary to the text rather than integral to understanding it.

Great release notes pay attention to detail in the visuals. You can achieve this by:

• Creating a preset for videos so that desktop background, cursor style, and padding are always consistent, even when different team members create them
• Using short, high-resolution gifs (the file size for longer high-res gifs will typically be too big. Uploading these can sometimes result in them being auto-compressed, which ruins the quality).
• Using fonts and colors from your brand guidelines

How to write release notes: structure and style

Ollie advises to keep a consistent structure between release notes — though don't be afraid to give extra space to key features when warranted. Generally, though, a set template makes it easier for your team to produce the best release notes, and easier for your customers to consume them.

"The way you structure your release notes can be a good indicator of your thought process there. This applies to documentation in general," says Ollie.

"Great products should really be reflected in good, detailed documentation. You'll notice that great products and great teams at a certain stage deliver really good docs most of the time."

Good documentation is structured clearly, organized logically, and clean and to-the-point.

Use plain language and formatting such as headers, bold and bullet points to make your release notes easy for customers to scan. Style-wise, your release notes are a brand touchpoint, and should use the same tone of voice and style guide as the rest of your customer-facing materials.

Release notes template

Introduction: Provide a brief summary of the update.

Header and short paragraph on new feature A. "You can now..." Include essential information on the feature, plus any relevant links, e.g. to your support docs.

Header and short paragraph on new feature B. "We've added X so you can..."

Header and short paragraph on improvement A. "As requested, we've added more Y to Z."

Bulleted list of bug fixes and issue resolutions: Discuss the resolved issues and their impact.

Known issues: Not every team includes this, but doing so can build trust if there's an ongoing issue that you're still working on, and want customers to know it's on your radar.

Important reminders or changes: Inform users about any critical updates — e.g. upcoming scheduled downtime.

How-to guides or resources: Provide supplementary materials to help users navigate the changes.

Call-to-action: Ask for feedback on your new release, invite people to discuss in your SaaS community, or show people where they can report issues — or simply include a support email contact.

If your release notes format includes a title, you can include the release date or latest version number here.

"There is variance in how teams like their release notes looks to look and feel. Some prefer a simple markdown doc, and others do something really branded. Find what works for you."

Release notes and community: customer feedback and the product lifecycle

"Every piece of content a company puts out can be used to encourage user engagement, from their community," says Ollie.

Release notes in particular provide a natural opportunity to invite users to give feedback, ask a question, report a bug, or make a feature request related to something in the changelog.

"Within the Outverse product, you can natively ship a changelog and promote discussion and feedback around it. It's a good flywheel," Ollie explains. "Especially for companies with a product-led or community-led growth motion."

‍

Release notes examples the Outverse team love

1. Medusa: a minimalist release notes example

MedusaJS takes a minimalist approach to release notes, and directs developers to GitHub (Medusa is a open-source framework). Their release note credits all contributors to the release.

‍

2. Linear

Linear’s changelogs are clean, visual, and tuck bug fixes away in a collapsible section at the bottom. They clearly explain how the impact affects the customer, and what you can expect when you next use Linear.

‍

3. The Browser Company (Arc): video release notes example

Notably, The Browser Company shares release notes in video form. It’s a great way of inviting discussion from the community and allows them to walk through new features in an engaging way. For those who prefer to read the release notes, they share them in the comments (and again on their website, where they link through to the video.

4. June.so

June’s changelog — as with all their brand comms — is written in an engaging, human voice and clearly describes the value of the new features. In this example, we love the explanation of the compromised involved in this v1: it builds trust and manages expectations at the same time.

‍

5. Example of release notes in Outverse

We use the native documentation suite in Outverse for our own release notes. This makes it easy to invite feedback in the community forums and close the loop with customers who have requested specific features. When you search an Outverse space, you search everything within it — so results can come from community posts, the knowledge base, or release notes like the above. We feel this more accurately reflects the way people search for product information, and makes it quicker for them to find the answers they need.

Writing purposeful and effective release notes can be a great way to open dialogue with your community and set them up for success with your product. Whether it's a minor bug fix or a game-changing feature, transparent communication fosters a relationship of trust and collaboration — one that benefits your business and customers alike.

‍