How to write excellent release notes
Last updated: May 2024
"Release notes have been published!"
This is the Slack message the Aha! team sees every Friday when release notes go live on our site. We publish weekly release notes to make it easy for customers (as well as team members and stakeholders) to quickly learn about new functionality, enhancements to existing features, and any bug fixes that our team delivered in the past week.
Our goal? Create an opportunity for education and connection — so that everyone understands exactly what changed in our software suite and how it makes their lives better or easier.
At least this is how our team thinks about release notes. But let's zoom out for a moment to talk about them more broadly. Release notes are a high-level summary of changes from a product's latest launch. Software or web companies typically publish them to share what has changed after new features go live. The audience consists of end users as well as internal and external stakeholders.
Streamline your release notes process. Try the release notes template in Aha! software.
Organizations approach release notes differently depending on their industry, size, type of product, and release cadence. But release notes are usually one component of a company or product's customer support knowledge base. (This can also contain support articles, product announcements, system broadcasts, how-to videos, and other self-serve resources for customers.) Depending on the organizational structure, several team members across product, product marketing, documentation, and engineering might collaborate to draft and publish release notes.
Jump ahead to any of the following sections:
What should you include in release notes?
Release notes are highlights — you are curating what is new and summarizing the benefits. Include only the essential information customers need to understand in order to use your product (think shorter than a changelog, but longer than a system broadcast). They might contain a mixture of text, images, screenshots, GIFs, videos, and links to relevant support articles or content.
Here is a closer look at how our team structures release notes:
New: a brief explanation of the highlighted feature of the week along with a screenshot and link to the go-to-market blog post announcing the new functionality
Improvements: any enhancements that the engineering team made to existing features
Fixes: bug fixes to pages that receive heavy traffic (such as the features board or ideas portals) as well as impactful support fixes
The release notes template in Aha! software makes it easy to quickly communicate recent changes to your product and get customers excited about new functionality.
When you are drafting release notes, it is worth thinking through the messages you are conveying — both explicit and implicit — with what you choose to cover (or omit). For example, it can be tempting to include just the team's wins, such as delivering major new functionality or a highly requested enhancement. But you then miss the opportunity to tell folks about a massive bug or even a paper cut that the team solved.
Related:
Finding the right balance between what to include versus what not to include in your release notes can be tricky. Focus on making it easy for customers to find the higher-impact or lovable updates. This will mean that you do not include every single improvement or fix.
What else should you not include in release notes? We suggest you skip the following:
Internal improvements
Marketing site changes
Security reviews
Work in progress
Minor bug fixes
A quick note on that last bullet: Companies can be reluctant to draw attention to minor bugs by announcing them — yet doing so can actually build trust with customers by making them aware of changes that might affect their daily work. To make our release notes as concise and impactful as possible, we tend to exclude bugs that nobody has reported, that most people are not aware of, that happen very infrequently, or that happen only in one account.
Why should you write release notes?
The short answer? To document and share relevant information about the product with customers, internal teams, and external stakeholders. But many product development teams either do not devote regular time to release notes or struggle to produce them. This can happen for a variety of reasons.
First, an organization must invest in a team (or depending on the size of the company, a team member) to write and publish release notes regularly. Similarly, it helps to have a purpose-built tool for tracking features and accessing corresponding release notes in one place.
Great release notes also rely on healthy cross-functional collaboration, which is sadly not the case at every company. Different groups in the organization need to work closely to accurately and clearly summarize new functionality and fixes. Mindset matters too. For example, some agile organizations mistakenly think that documentation will slow them down, so they might ignore release notes in favor of moving on to the next thing.
Companies that write release notes do so for the following reasons:
Auditing: keeping a public changelog of what was released or fixed and when
Branding: regularly sharing content in the company's voice/style about its product
Conversion: encouraging prospects to learn more about the functionality so they start trials, and inspiring existing customers to use a product in new ways (or buy additional products)
Obligation: writing release notes just because other companies do and it is expected
None of these are "bad" reasons to write and publish release notes. But it is important to remember that release notes are primarily an opportunity to educate and connect with the people who care about your product: both customers and team members.
Release notes are also a great way to capture product information that should be updated or revised in other places, such as user guides, marketing assets, and training materials. If you use release notes in this way, you can help contribute to a more cohesive Complete Product Experience for customers — ensuring the information they see at different touchpoints is accurate and consistent.
Best practices for writing release notes
When drafting release notes, we aim to adopt an audience-centric point of view. This means tailoring the content and tone to our customers and what they need from our product. What does this look like in practice? As a B2B SaaS company, we use a professional, efficient, and encouraging tone in release notes to match the preferences of our company and customers. Although a company with a more casual product might publish playful or creative release notes, ours focus more on sharing vital product information and customer lovability.
Writing with customers in mind also means thinking holistically and building narratives. Instead of treating each release note as its own distinct list, try to batch related updates as part of a larger story. For instance, you could group decreasing page load times across the app over several weeks into a single update or article. This makes for a more cohesive and digestible reading experience.
If you are looking for ideas on how to improve your own release notes process, here is an overview of our knowledge base team's approach:
1. Scope
Product managers or developers flag potential features to include in upcoming release notes. The knowledge base team also reviews all features shipped in the past week.
2. Define
The knowledge base team then creates a list of potential items to highlight in release notes. Team members consider what will be the most impactful information to include for customers and stakeholders.
3. Draft
Technical writers create a first draft of the release note. Then, a product manager or developer, as well as the knowledge base team lead, review and offer feedback for improvement. After the content team edits the release note, we publish it on our website.
Here are a few specific tips from our team:
Link release notes to your company and product vision as well as your content strategy. Consider why you publish release notes in the first place and what you want to get out of them.
Keep release note names simple. We follow a "[Date] release notes" format. (Because our team continuously deploys, we publish weekly and do not version release notes.)
Ensure consistency. The release notes template in Aha! software helps teams quickly create a repeatable and customizable summary of product updates. Everything should be organized in a logical way that is easy for readers to understand.
Leverage AI when possible. Instead of drafting from scratch, we use our own AI-powered release notes to quickly summarize and draft what is new. AI helps generate a rough draft of release notes based on features in Aha! Roadmaps that the team recently completed, and our team polishes the notes before publishing.
Release notes can be a valuable tool for telling your customers and team members what they need to know to get the most out of your product. If your organization does not do so already, consider storing all of your release notes on a single website page. This makes it easy for folks to quickly find and search through an archive of your product updates and enhancements. You can also give customers the option to subscribe to your release notes so they get an email or in-app notification when new features are released.
