You’re in the home stretch of your release cycle. It’s time to ship your product...and you have to write release notes.
By the time many SaaS product teams reach the end of a release cycle, they treat the release notes as an afterthought. They rush to put something—anything—together to check the “release notes” box of that particular development cycle.
The release notes either end up being full of technical jargon users will not understand (and tune out), or they don’t clearly articulate the value of the updates, fixes, and new features being made. That’s a big mistake because…
Release notes are an opportunity.
They’re an opportunity to keep your customers excited about their investment in your product. They can drive adoption of new features and functionality, reduce concerns about bugs or known issues, and even be a powerful marketing tool.
In this article, we’ll look at what release notes are, who should write them, and how you and your users benefit from good release notes. And don’t worry, we’ll be diving into real examples and a template you can steal for your own release notes.
What are release notes?
A release note is a report published alongside new or updated software that details the technical features of the product. For new releases, these notes provide end-users with a brief summary of the product itself. For updates to existing products, the notes educate end-users the notes educate end-users on what’s new and how the product has been improved since the last release.
Release notes are often distributed to users on a designated page within the app itself, which is often called a changelog. This approach allows for companies to maintain comprehensive lists of changes to their software going back to the product’s first version for their customers.
Keeping these running lists shows customers that a product is in a constant state of improvement and that recent changes clearly build on older upgrades. It also tells customers that the company behind the product listens to its customer feedback and is dedicated to providing the best possible customer experience.
Who should write release notes?
The product management/development team or technical writing team, which is in constant dialog with the dev team, are usually the ones responsible for writing the software release notes. It’s more common to have a dedicated technical writer or team of technical writers in larger orgs.
The product or development team is responsible for release notes because they’re the most familiar with the changes and enhancements that have been made to the software. They have a deep understanding of the technical details of the software and can provide accurate and comprehensive information about the changes that have been made from one version to the next.
Additionally, these teams are responsible for writing documentation for the software, so having them transform that documentation into externally facing release notes isn’t too much of an extra effort for them.
The importance of good release notes
Good release notes can:
- Enhance the user experience by providing clear and concise information about the changes in the software and how they impact users’ workflow. This can help users more easily adopt the new features and understand how to use the software effectively.
- Improve the reputation of the product and your company. By providing thorough and accurate information about the changes in the software, companies can demonstrate their commitment to transparency and user satisfaction.
- Reduce the burden on your support teams to answer questions about known issues or feature requests or put out an issue summary.
- Help users and organizations plan for updates and upgrades to the software. When users can see what’s on the product roadmap, it helps them justify renewing their subscription, adding users, and upgrading to higher tiers of service.
- Build excitement for new features and products. Release notes can tease new enhancements to your product and serve as another tool in your marketing team’s toolbox to engage users.
How to distribute release notes
Forcing customers to journey through your app to find important release information can be disruptive to UX. Requiring them to dig through docs or endure a barrage of notifications and popups is also not ideal.
You can usually distribute release notes in your software or app when users log into the latest version.
Sometimes, other methods of distribution should be used to reach users, including:
- Email. These can be used to directly communicate updates to customers instead of waiting for them to use your product. They’re often used to celebrate exciting updates or announce important changes to the status quo.
- Blog posts. These are designed to handle longer-form content than a standard email or in-app message. This makes them a perfect format for releases that deserve more copy or explanation.
- Tutorials and user guides. Use tutorials to explain new UX or features. This will draw attention to them and ensure users don’t get confused if something looks and feels different.
- Social media. This is a great way to spotlight single features and build hype for new releases and updates.
- App Store/Google Play Store. Release notes are common in Apple’s App Store and the Google Play Store. For example, users looking to buy or update a web or iOS app in the App Store can view an extensive list of release notes when selecting a product. The TikTok app version history looks like this:
Distributing release notes using Appcues
Companies also have the option to deliver release notes through in-app messaging. A customer receiving an email or browsing a blog post is reading about the new features and experiencing them later. In-app messaging, on the other hand, allows a customer to read about the new product or updates as they are experiencing them within the app itself in real-time.
After installing an SDK, companies can use Appcues to easily deploy in-app messaging features that deliver release notes. For example, modal windows can be deployed when a user first opens the app or pulls up a new feature that gives an overview of the changes in store. Slideouts are often used to explain new features or changes to the UI as users engage with the elements in question. Companies can also use the Appcues API to import historical events and user property data or configure advanced segmentation (i.e., targeted messaging).
Bottom line: each of these options provides an explanation of new or updated features before a user has the chance to be frustrated by them. Appcues in-app messaging makes it easy to deliver release notes that explain even the widest breadth of changes without bogging the user down in modals and slideouts. Release notes are key, but shouldn’t come at the expense of good UX.
How to write release notes
Release notes have the potential to inform and even delight your users or frustrate them with vague updates or indecipherable jargon. Luckily, adhering to a few simple tips can elevate your release notes from “Ooookay...” to “Okay!” in a jiffy.
1. Use a Release Notes Template
There’s no need to reinvent the wheel with release notes. Even though they offer ample opportunity to communicate your unique value to your users, all release notes should include the following:
- An introduction header and brief overview of the changes
- A clear explanation of impacted users
- Changes to previous release notes
- Feature enhancements or new features/functionality
- Fixed issues
- Ongoing issues/challenges/obstacles/limitations, and a plan on how the changes will be made.
Here’s one we created that can assist you in your release note writing.
Download the Appcues Release Notes Template PDF.
2. Make the intent of the changes clear
The people who scan release notes are there for a reason—they want information on what's been changed in the latest release and how that affects them. Make sure the text clearly shows what’s been changed, and highlight what those changes mean to the user. Also, don’t be afraid to use some humor to put the user at ease.
Make sure the text clearly shows what’s been changed, and highlight what those changes mean to the user. Also, don’t be afraid to use some humor to put the user at ease.
Clarity is key in your release notes. You need to find a balance between providing enough detail and not overwhelming users with big, confusing blocks of text. Web users don’t read—they scan—so make your release notes scannable. One way is to highlight important keywords you want the user to notice.
Keep explanations short and simple, but don’t oversimplify. For example, saying, “Bug fixed and updates applied” is short but vague. On the other hand, “We improved the ability to switch apps, reducing unexpected software crashes” is clearer, highlights the benefits in more detail, but still isn’t too long or overwhelming.
3. Focus release notes on the user
When compiling your notes, your focus should be entirely on the user. What information do they need? Can they easily find it in your note?
Keeping their needs top-of-mind when writing them will help you relate to your user and keep your updates engaging and easy to read. The user is more likely to understand your changes and will pay more attention to your release notes.
It’s important to know your customer—77% of consumers would preferably purchase from brands that share their values.
4. Explain changes with visuals
Most consumers only remember about 20% of the text they read when it's not accompanied by visuals, and according to one eLearning website, “ well-selected images can improve comprehension and insight when developers strategically place such graphics.” If your release notes need a lengthy explanation, include a short GIF or a helpful screenshot that shows exactly what that change does.
An example would be the Magic: The Gathering card game release notes. One release notes update contains as many as 51 pages of update information— it’s a lot to take in. However, MtG has done a good job of summarizing those notes on their front page with visuals and recaps of the most important features that were updated.
5. Keep release notes organized
Users will become numb when asked to read or scan a wall of text. Keep things organized and segmented by using subheads, drop-down menus, bullet points, and paragraph breaks. Breaking up big blocks of text in your release notes will help the user readily find which change applies to them.
A good example is Amazon Business, which has a dedicated release notes page that allows drop-down menus to segment notes by category, product name and offering, and release date.
6. Don’t get overly technical
Release notes can serve different purposes—promoting new features, building a relationship with the customer, helping users find solutions to their problems—but it’s hard to do that when notes are peppered with highly technical and difficult niche language.
Unless you know for sure that your users will easily comprehend technical/specialist language, it’s better to ease up on the jargon.
Use straightforward, easily understandable words and phrases. Once you’ve finished writing, read the release notes out loud to a friend or family member—someone who doesn’t know about the technical background of the release. Does the explanation make sense to them?
Chances are, someone unaffiliated with your product or company gets what you're talking about, so will most of your users. “You can now use GIFs in our messaging service” is far more understandable than “We have implemented the ability to use Graphics Interchange Format bitmap images which includes file compression, transparency, interlacing and storage of multiple images within a single file for our messaging service.”
Use jargon-less notes as a way of connecting with the customer. If your brand is funny and light-hearted, your notes should reflect that. If your brand is eco-aware and green-friendly, adopt that messaging in your release notes as well. This consistency will resonate with customers who are familiar with your brand and drive loyalty.
7. Promote your brand...carefully
You can use release notes as a way to promote your brand messaging, but don't overdo it with heavy self-promotion. Too much self-promotion can erode a customer's trust in your brand. But can you sneak a little self-promotion into your release notes to help boost your brand's messaging.
Be careful how you pitch, though. A poor pitch in the release notes inflates the brand and overpromises before mentioning the change. “We’re here to save the planet, something we've done successfully with every updated release. You're welcome. Our new hotfix includes 50% less energy consumption.” It comes across as arrogant, a real trust-killer with your audience.
Instead, a softer (and more humble) approach would be “Bugfix: 00100 — Software now reduces end-user energy consumption by 50%. One of many ways we aim for a sustainable future.” You see what we did there? We told you the fix, then threw in that we’re watching out for you--all without sounding performative.
Employ the 80/20 rule used in social media; 80% of your content should be useful, and only 20% should be self-promotion. This rule is not only useful for release notes but for any type of content you produce.
5 examples of great release notes
The format of your release notes should be a balance of meaningful content and a reflection of your brand’s voice. Below are five examples of great release notes and an explanation of how you can emulate them to make a bigger impact with your next update.
1. Help Scout reminds users of existing features
While announcing a new feature (a bulleted list), HelpScout also draws users’ attention to Messages editor features some may not be currently using.
The screenshot shows how the Markdown feature is used with an example and how the link on the word Markdown takes the user to an in-depth article on the feature. When composing release notes, the Markdown feature is helpful in pointing out where the user should be looking, eliminating aimless searching throughout the document.
2. Retool categorizes types of changes for easy user skimming
Retool categorizes their updates as “Minor,” “Improvement,” and “New.” If a user wants to focus only on “New” features within the list, they’re easy to find.
Each release note section has a spot for users to leave feedback, so Retool can capture user sentiment about a release. This kind of feedback loop is essential in developing even better release notes because you can address exactly what the customer did or didn’t like.
3. UiPath includes a Table of Contents for easy navigation
The ease-of-use UiPath offers with its table of contents feature makes the navigation of the release notes even easier. If users have questions about past releases, they can easily access the release notes table of contents.
4. Amplitude incorporates video
Amplitude uses a combination of short videos and screenshots when explaining new features. Video is very effective when engaging an audience. 79% of people say watching a video has convinced them to buy an app, and “explainer” videos are viewed by 96% of consumers.
Amplitude’s animated intro gives users an explanation of the new feature first and then dives into the application to show the feature “in action.”
5. Feefo’s in-app update announcement gives you the release notes immediately
Some users don’t want to scrounge around a lengthy release note document on your website or through email. Feefo uses Appcues to announce its latest features, releases, and announcements in the app itself. This communication is especially effective since the app is where the changes will have the biggest effect.
The slideout grabs attention and notifies users about updates without taking them out of the app itself. Users can click a button to access the full release notes.
Find out how Appcues can help you improve your activation rate, increase campaign opt-in, and reduce support burden through contextual, targeted in-app communication.
Make a bigger impact with great product release notes
Appcues can help manage the weary chore of writing release notes. Their in-app user engagement platform can help take the most technical task and simplify it for your teams while skipping the part where you barrage your IT department with requests.
Want help planning the perfect product launch? Try our Product Launch Planner tool for free!
By the time most SaaS product teams are at the end of a release cycle, they treat the release notes as an afterthought. They rush to put something—anything—together to check the “release notes” box of that particular development cycle.