When you improve your product, remember to tell the world about it! Otherwise, people may not notice.
One of the best ways to do that is through product announcements. There are a few different types of them.
A release note is a document that outlines the changes made to a product. Release notes update your users, teammates, and stakeholders on your product development progress.
Changelogs are more technical documents that dive deeper into the changes. They’re primarily for developers to keep track of progress.
We’ll cover different types of product release notes and changelogs, their importance, and best practices. We’ll also showcase some examples and templates, discuss changelog management tools, and help you get the most out of your feature announcements.
If you’ve never published release notes or want to improve your product documentation, follow along.
Contents hideFirst off, let’s go over some definitions.
What are release notes?
As mentioned, release notes are basically your product announcements. The target audience is users, so release notes explain changes in plain language, omitting the technical jargon and details. The main purpose is to explain the effect on the user.
A changelog is a file, an article, or a webpage that lists all notable changes to your app, site, etc. Changelogs focus on the technical aspects of the changes, such as new features, bug fixes, code refactoring, and API modifications. They often contain references to specific commits or code changes in the version control system.
Historically, changelogs were for developers. Here’s a typical changelog entry from Facebook on GitHub.
Some people refer to changelogs as release notes. And others make a distinction between these two terms.
Canny’s Changelog tool blurs the lines between release notes and changelogs.
“Coming from the product development world, we saw the need for better product announcements. Users want to know what’s new and improved in your product. And we needed an easy tool that helps us do that. So we created our own tool – for us and other SaaS companies out there. It brings customer feedback and product announcements together.”
Andrew Rasmussen, co-founder at Canny
Whatever you call your product announcements, it’s important to have them. Here’s why.
Changelogs and software release notes are important for:
Here’s more about each of those reasons.
At its core, release notes help your team stay organized. When you have release notes, you can quickly reference them to see what was changed in the past and how.
You’ll also minimize the back and forth with your team through release notes.
Not every project involves all team members. So, release notes are a great way to keep uninvolved teams informed. They’ll learn about changes as soon as you publish your release notes.
New feature adoption is a common problem for a product manager. Many users crave efficiency but are still hesitant to try new things.
Release notes help push them in that direction. They break down the new feature, guide users through it, and remind them how your tool works. A good release note is a free teacher.
Release notes are also an opportunity to link to additional help docs and remind users where they can find support resources.
When people use a product, they like to see it evolve. Right now, for example, AI is all the rage. Many tools are adding AI components to their software. And at this point, users are almost expecting it.
If you decide to add AI to your tool, you’d want your users to know about it, right? There’s no point in putting in all the hard work if no one notices. You want your users to know and use these new features.
Especially if your product uses a subscription model, people want to see it updated. Consumer demands change, and your product needs to measure up.
From minor design improvements to major feature enhancements, your tool will go through many iterations. So let your users know about it. Show your progress and invite your users to join you on this journey.
Release notes are a great way to do that.
Similar to the previous point, release notes help you keep your customers around. Here’s how.
Bonus: they can see other updates in your release notes too.
This shows that you listen to your users. That’ll help them trust that you’re improving your product.
People love seeing the “behind the scenes” and “how it’s done” content. Release notes can shed light on your “backstage” software release processes.
Overall, release notes are pretty standard and straightforward. Depending on the nature of your new release, you can borrow certain parts from each release note entry (which is what we did with Canny’s Changelog).
There are a few types of posts you’d add to your release notes. Let’s discuss each one.
Intended audience: users, leads, team members, shareholders
When you’re adding a major new feature, make sure to give this announcement the attention it deserves.
These release notes can be longer and include more details, such as:
Note: Give users some time to get used to the change too. Many tools keep the old (legacy) version available for some time for this exact reason.
Intended audience: current users, team members
You can keep it simple when adding or fixing something less groundbreaking. Make sure to explain why you did it( we often show how many upvotes we got on our Canny board, for example).
Explain what changed, but don’t go too deep into the technical details. Instead, link out to help guides and additional resources.
Intended audience: developers, current users
Bug fixes are a great example of non-major feature enhancements. You don’t want to draw too much attention to the fact that you had bug reports. But let’s be real – every software has them. And showing that you’re working on them makes you look transparent and trustworthy.
Intended audience: current users
While very important, security updates fall under the category of non-major updates. They showcase your organization as responsible and reliable.
Very few people want to read lengthy descriptions of your security updates. So it’s even more important to keep these short.
Intended audience: developers
A standard changelog is detailed and technical. It usually includes:
Developers use changelogs to schedule upgrades, troubleshoot issues, and stay updated about the latest software developments.
Intended audience: developers
There are a few terms that people use interchangeably to describe these updates:
These are records that keep track of changes made to a project or set of files over time in a version control system (VCS).
A common example is GitHub. Developers use it to share code, work on projects together, and manage and track code changes.
Github logs are visible to the public. This is a space where developers can collaborate and share ideas – kind of like social media for coding.
Version control system logs usually include the following information:
A project’s version control logs are crucial to tracking and understanding its history.
If you’re looking for more inspiration and ideas, BroadInstitute provides great sample changelogs. Check them out here.
Different companies use different formats for their product announcements. Depending on your product and audience, you can pick a format that works best for you. It’s important to choose a format and stick with it. We’ll explain why consistency is so important later in the article. First, let’s walk through the various formats.
This is the simplest and most common format for a software release note. You can simply create a text document that lists the changes in reverse chronological order (put the newest releases at the top).
Each entry should include the version number, a brief description of the change, and any relevant details.
This format is easy to create and read for most users.
If you prefer a more technical approach, you can follow a typical changelog format. You can include categories like:
This format is particularly useful for developers and technical users who want a quick overview of the changes in each category.
With a changelog tool, you can also create HTML files for example.
Markdown is a lightweight markup language that helps you format text quickly and easily. You can write release notes in Markdown and easily convert them into HTML or other formats.
If you’re hosting your updates on a platform like GitHub, you’ll likely use the Markdown format.
HTML provides a bit more flexibility with styling and layout. You can include links, images, and other multimedia elements, making your release notes more visually appealing.
PDF is a good option if you need to share your updates with external stakeholders or use them in official statements. The layout and formatting stay consistent, and it looks presentable.
PDF is easy to read, print, and share across teams.
Depending on the format you choose, consider including the following elements to make your announcements more engaging.
You can create a series of bullet points, each bullet representing a specific product change or a feature.
If you’re looking for a concise and skimmable format, this is it. It gets straight to the point.
We recommend combining some written descriptions with visuals like screenshots and GIFs. They break up the text, help visual learners, and tell a story better than words can.
With screenshots, we recommend drawing readers’ attention to the part that you’re talking about. You can add boxes around the most important parts and/or blur the irrelevant parts of the page. Here’s an example.
Creating a quick video walkthrough can make your feature update even easier to understand. Some people are visual learners, so they’d enjoy seeing rather than reading.
There are a number of ways to generate release notes.
1. Version Control System (VCS) history
Version control systems like Git allow you to generate release notes based on commit histories. For instance, you can extract commit information using the git log command with specific formatting options, such as dates, authors, and changes.
2. Commit messages
Encourage your developers to write clear and informative commit messages describing each commit’s changes. Following a consistent format, such as the changelog format, can be helpful.
3. Integration with issue tracking systems
You can automatically create release notes by connecting issues and pull requests to versions or milestones in your issue tracker. You can use tools like Jira or GitHub for that.
4. Manual changelog
You can manually keep track of the changes you make to each version. You’d need to maintain a separate file where you add entries for each release, including the added features, changes, and bug fixes.
5. Automated tools
You can generate a structured and formatted changelog with these tools. They analyze your commit history, tags, and metadata. Some popular changelog generation tools include:
This tool follows the conventional commit message format and generates changelogs.
This tool is designed to generate changelogs for GitHub repositories.
This project provides guidelines and a tool-agnostic format for writing changelogs. It also offers a Python library called towncrier for generating changelogs.
6. Canny’s Changelog
Canny’s Changelog is different. It’s designed so that everyone, even non-developers, can:
It’s much more visual and concise than most other changelogs. And it looks like a newsfeed, not a developer portal.
Canny’s Changelog is available on all plans! Here’s what our clients say about it.
Our changelog lets you easily tie your feature requests with product updates and notify your users.
Here are a few more guidelines to make sure you publish engaging and effective release notes. Follow these tips if you’d like your release notes to be an asset instead of a burden.
It takes time to find the time, energy, and motivation to read long texts. It’s even more true when it comes to technical language.
If you want your release notes to be a truly useful source of information, make them as straightforward as possible. Answer the following questions:
Simplify your language, keep sentences short, and break up the long paragraphs.
As a general rule, stick to only relevant information. It’s easy to get very involved and start describing the whole history of your tool. But leave that for another day.
Remember: even if your product is technical, you might have non-technical users. So try to make it interesting and valuable for them as well.
Some changes might be more significant than others. Still, try to publish most of your updates as release notes. People appreciate your updates – they’ll feel like they’re with you on your journey. They also get a sense that you’re constantly improving.
This will also keep you accountable. Knowing your users expect consistent updates will make you hit your deadlines more often.
Also, keep the format of your release notes consistent. Here’s an example from Keepachangelog:
Use a variety of formatting to make your release notes entries even easier on the eye.
Headings help break down the text and logically group the changes. So does white space.
Text formatting (bold, underlined, italics) highlights the most essential parts and helps readers skim the text. Bulleted and numbered lists have a similar effect.
Always publish the latest changes at the top – that’s the most relevant information for your users. They can scroll down to see your historical progress too.
Often, it’s easier to show than to describe something. Visuals like screenshots, GIFs, and videos can help here. Moreover, they’ll familiarize your users with the new features quicker. Next time they log in, they’ll remember the visual and know how to use the new feature.
Visuals also break up the text and make reading easier and more enjoyable.
We keep repeating that release notes need to be short. But what if you’ve released a major change and need to explain it in detail?
That’s where you insert links to in-depth help articles and additional documentation.
You can also use your release notes to keep your users engaged. While they’re hooked, don’t let them get away. Link to related resources and keep them on your site longer!
We can’t stress this enough: make it simple. Here are some tips to help you do that:
If you’re using Canny for your product announcements, your users will get automatic notifications when a new changelog is published.
Still, you can amplify the message further. Involve your product marketing team – they can help spread the word.
Now that you know what makes good release notes and changelogs, let’s illustrate it with examples.
Many of our clients use Canny’s Changelog tool. They find it easy to keep users up-to-date in one central location.
“When we built our Changelog, we wanted it to be more than your typical list of changes. We created a tool that helps you close your customer feedback loop.”
Sarah Hum, co-founder at Canny
When a new changelog entry is published, everyone who submitted, upvoted, or commented on this request gets an automatic notification. That includes current users and prospects. And this really makes the sales job easier.
Imagine this: a lead previously requested a feature and didn’t convert because it didn’t exist. Now they’re getting a notification that this feature is shipped. If that feature was a real dealbreaker to them, they might reconsider buying from you now.
Your current users will also find out about the new feature right away and will be able to try it out.
Canny’s changelog empowers you to follow our advice above, including custom formatting.
Here’s what it looks like.
AgencyAnalytics keeps their updates brief and to the point. When they introduce new features, they include visuals to keep it engaging and break up the text. See some examples of great release notes below.
We love ClickUp’s use of emojis and links – it keeps the readers engaged and curious to learn more. Notice how they link out to release notes and more information. They don’t clutter their changelog entry with it.
CommentSold’s changelog entries are typically longer, but they’re still easy to read and understand. It’s a great example of a more detailed but still digestible changelog. They walk you through the steps you need to take, and text styling (bold text in this instance) makes it easier to read.
Hive is great at telling a story in their changelog. Here’s what wasn’t working, how we fixed it, and how it works now. We love how they show a screenshot of a feature request that led to the development of this feature.
Respond.io is another example of a short and highly visual changelog.
GitHub’s changelog is another great example. They also have a separate Twitter account and an RSS feed for users to follow along the journey. It’s important to be where your users are!
We use our own changelog too!
Sometimes, it’s still hard to get going. That’s why we’ve prepared some templates – check out the next section.
If you’re inspired to get started or amplify your changelog (and we hope you are!), check out these templates. They’ll give you prompts for your release notes, changelog entries, and some examples to spark that initial motivation.
Here is a release notes template for a bug fix.
And another release notes template to announce a new feature.
There’s no better way to keep all your stakeholders involved, engaged, and updated than through release notes.
Product update announcements don’t need to be a hassle. With a changelog tool like Canny, you can keep track of all your progress and delight your customers at the same time.
Book a free Canny demo and see how easy it is!
