Why do you need release notes? (featuring great examples and templates)

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. 

Release notes vs changelogs

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

Why do you need product announcements?

Changelogs and release notes are important for:

• Documenting your work
• Educating your customers
• Keeping your products updated
• Positioning yourself as transparent

Here’s more about each of those reasons.

They document your work

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.

They educate your users

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.

They make the product feel fresh

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.

They help you be transparent

Similar to the previous point, release notes help you keep your customers around. Here’s how.

1. A user submits a feature request
2. That feature idea makes it to the product roadmap
3. They automatically subscribe to the progress of that feature
4. You build that feature and publish a release notes entry
5. They get an auto-notification about it (if you’re using Canny’s Changelog)

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.

Types of product announcements entries

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.

Major update announcements

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:

• Before and after screenshots and screen recordings
• Clear explanation of the change

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.

Non-major update announcement

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.

Bug fixes

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 bugs. But let’s be real – every software has them. And showing that you’re working on them makes you look transparent and trustworthy.

Security updates

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. 

Changelogs

Intended audience: developers

A standard changelog is detailed and technical. It usually includes:

• Version number
• Release date
• Description of the latest release or a fixed bug
• Compatibility with previous versions
• User impact
• Manual for future use
• Screenshots and links

Developers use changelogs to schedule upgrades, troubleshoot issues, and stay updated about the latest software developments.

Version control system logs

Intended audience: developers

There are a few terms that people use interchangeably to describe these updates: 

• Version control system logs 
• Commit logs
• Revision history

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:

• Commit ID: a unique identifier for each change or commit made in the VCS. Typically, it’s a hexadecimal string, such as a SHA-1 hash.
• Author
• Date and time
• Commit message: a descriptive message that summarizes the purpose or nature of the changes made in the commit
• Changes: a detailed listing of the modified, added, or deleted files in the commit + specific changes made to each file. This may include line-by-line differences or a unified diff format.
• Branch or tag. Branches are different lines of development. Tags indicate specific points in the version history – releases or milestones for instance.
• Merge information: if the commit involves merging changes from multiple branches, the log will contain information about the branches involved.

A project’s version control logs are crucial to tracking and understanding its history.

Developers can:

• Find the record of all changes
• Review and revert to previous versions
• Figure out who made specific changes
• Understand the evolution of the codebase over time
• Coordinate work and collaborate
• Resolve conflicts when merging changes from multiple sources

If you’re looking for more inspiration and ideas, BroadInstitute provides great sample changelogs. Check them out here.

Product update formats

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.

Text file

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.

Changelog format

If you prefer a more technical approach, you can follow a typical changelog format. You can include categories like:

• Added
• Changed
• Fixed
• Removed

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

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

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

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.

What to include

Depending on the format you choose, consider including the following elements to make your announcements more engaging.

Bullet-points

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.

Visuals

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.

Videos

Creating a quick video walkthrough can make your updates even easier to understand. Some people are visual learners, so they’d enjoy seeing rather than reading.

Generating release notes

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:

• Conventional commits

This tool follows the conventional commit message format and generates changelogs.

• GitHub Changelog Generator

This tool is designed to generate changelogs for GitHub repositories.

• Keep a Changelog

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:

• Add entries
• Easily understand it
• Quickly find what they’re looking for
• Sort the entries
• Find more information

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.

[insert a GiveButter case study clip about the changelog]

Our changelog lets you easily tie your feature requests with product updates and notify your users.

Best practices for release notes

Here are a few more guidelines to make sure you publish engaging release notes. Follow these tips if you’d like your release notes to be an asset instead of a burden.

Make them clear & concise

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:

• What was the problem?
• What changed?
• Why does it matter?
• How does it affect the user?
• Where can they learn more?

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.

Post consistently

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.

Format consistently

Also, keep the format of your release notes consistent. Here’s an example from Keepachangelog:

• Added new features
• Changed for changes in existing functionality
• Deprecated for soon-to-be-removed features
• Removed for now removed features
• Fixed for any bug fixes
• Security in case of vulnerabilities

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.

Follow reverse chronological order

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.

Use visuals

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.

Insert links

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!

Avoid confusion

We can’t stress this enough: make it simple. Here are some tips to help you do that:

• Stay away from confusing date formats (we recommend sticking to YYYY-MM-DD format)
• List deprecations, removals, and any breaking changes
• Document only noteworthy differences
• Don’t list commit log diffs

Involve other departments

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.

Release notes and changelog examples

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

Release notes and changelog templates

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.

To get these + more editable templates, download our free Changelog templates right here!

Why product announcements are important

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!