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.
Top
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.
Top
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.
