January 23, 2022
How to Write A Good Changelog
Changelogs are one of the best ways to keep your customers updated on your product journey. Here’s how to write your best possible changelog.
Changelogs are one of the best ways to keep your customers updated on your product journey. Here’s how to write your best possible changelog.
Changelogs are one of the best ways to keep your customers updated on your product journey and loyal to your company. But a bad changelog can do more harm than good. So here’s how to write the best possible changelog or release notes for your product.
Changelogs and release notes are chronological records of all the fixes, updates and additions made to your product. Software companies will often publish their changelogs to keep users in the loop about changes they make to their product, but they’re also useful for development teams to help them keep track of what edits they’ve made as well.
Release notes tools help you build and update your changelog without the hassle of changing code or manually adding individual release notes. They work by making it easy for you to share product updates with your customers to keep them in the loop and educate them on new features. In turn, you can close the feedback loop and boost communication with your users, driving more engagement in the process.
There are a lot of great examples of changelogs that can help you figure out what to include within your own. Here’s some of our favourites.
TickTick cleanly formats their changelog with tags that differentiate between new updates and improvements on previous features. It’s a small but great way to help users skim through their changelog and find what they need.
HelpScout has changelogs for several different products, but the one we want to focus on in this post is the changelog for their mailbox API. They keep their main changelog short and readable by linking out to longer pages, so users can read over the summaries and then click on individual items they want more info on.
Percy differentiates their changelogs from others by including images in their updates like product screenshots or gifs. It’s a great way to break up walls of text and call attention to individual updates.
Intercom’s changelog is great because it’s clean, well-organized and skimmable. Like some of the others on this list, they show shorter versions of their release notes on the main page that you can click on to read more about. They also have a sidebar for categories to let users find what they need more easily.
Release notes will be unique to every team and company, and there are no set rules on how to write them. But here are a few suggestions that can help you create your best changelog possible.
Above all, your changelogs need to be clear and easy to read. One of the easiest ways to do this is to make sure all your changelog updates are in chronological order, dated, and organized by update or issue in order to make it easier for your users to find new updates and locate older ones.
There are a couple other things you can do to make your changelogs look more visually pleasing and easier to skim. You can separate large blocks of text–the explanations of what you’ve changed or fixed–with headings and subheadings, and break up long sentences and paragraphs as well. Bullet points are another great way to make specific details easier to read or to summarize key points to help your customers understand what you’ve done.
While images are a great way to break up your changelogs and make them more readable, they’re also a great way to help showcase the changes you’ve made to your users. Describing your updates is one thing, but it can be hard to truly convey what you need to without using visual aids–especially if your audience isn’t as tech savvy as you are.
One of the most common problems with changelogs is that they can easily become disorganized and hard to sort through. Though there are several different ways to format your changelogs, you’ll need to pick one and make sure to stick to it. Mixing formats or not using one at all can easily make your changelogs unreadable.
Likewise, it’s important to make sure you date each release. Your customers will want to know what was changed and when, and it’s also a great way to make sure all your updates are in the proper order.
We’ve already touched on this a little bit, but it’s important to find a way to group or order your changelog releases. Is this a new feature? A bug fix? What area of your product does it focus on? Think about these questions and come up with a logical way of sorting your changelog entries and stick to it.
We’ve used both “changelog” and “release notes” interchangeably in this post, and for the most part, that’s how the terms are commonly used. But some also describe changelogs as more technical and detail-specific, while release notes are more explanatory. Most companies only have a changelog or a release notes (or use those terms interchangeably), but some have both. So while it’s not necessary to create both, it’s up to you to decide what works best for you.
Usually, the product development team will prepare the release notes, or at least gather up all the info necessary to write them. Sometimes, though, larger products will have copywriters or editors to put together the notes for release. It’s all up to whatever works for you and your team.
Like changelogs, release notes are often distributed on dedicated pages to make it easier for customers to locate these releases and stay up-to-date.
Though we’ve already talked about some of the benefits of using a changelog tool, let’s go over a few reasons why you should use a changelog tool once more.
Changelogs are a great way to centralize your updates and issue releases all in one area. This means your users will know exactly where to go to find the information they need and what page they can rely on for this information.
Changelogs are a crucial part of your feedback loop. Being open with the changes to your product is just as important as getting feedback from your customers; it has to go both ways in order to form a reciprocal relationship.
The process of writing and creating a changelog itself can be a great way to boost internal documentation for your product and keep track of all the changes you’ve made. This will help you record your product journey and be able to easily track down what changes were made and when.
Lastly, changelogs offer an easy way for you to announce new features and updates to your product. In a way, it’s kind of like a message board for your product; customers can check it at their convenience and find out what’s new and what they need to know about your product.
They’re also a great way to show shareholders your growth and product journey. Changelogs lay out all the updates and changes you’ve made to your product in a linear fashion so you can easily show off all the work you’ve done.
At UserVitals, we use our own changelog platform to host our release notes.
We offer two ways to communicate changelog updates to your users. One is a dedicated changelog page that hosts all of your release notes together on the same page to create a dedicated knowledge page for customers. But we also recently released a changelog widget you can embed onto your site so viewers can quickly see any new updates on your homepage and click on them for more info.
Setting up your changelog with UserVitals is easy.
First, head to the Changelog tab in our app; this is where all of your changelog entries will be located, formatted by both date and type (more on that later). To add a new changelog entry, click on the New Draft button at the top-right corner of your screen. Give your changelog entry a title, and then head to the next screen where you can fill out the details of your entry and add a hero image to help describe what the changelog entry is about.
Within the details section, you can format the text however you like and include everything from text markup to links to headings. You can also add custom labels and entry types to your entry (for instance, app design or bug fixes).
Once all of this is done, simply click Publish and the entry will be automatically added to your changelog. You can add as many entries as you’d like–there’s no limit.
Once you've set up your main changelog page, it's easy to add our widget to your site.
To do this, first head to your UserVitals app dashboard and click on Settings and then Changelog.
Once there, click Generate under Widget Token & Snippet to generate the code you need to embed in your site. From here, we have help pages to show you how to embed this code on Webflow, Wix and Wordpress.
Once you've followed these steps, your changelog widget will automatically show your three most recent changelog updates on your homepage.
Though we allow you to backdate old changelog entries to get your release notes up to speed, you can also publish changelog entries alongside new product releases. Get a list of all the updates, flesh them out with a little more info and some pictures to illustrate what you’re talking about, and then tag them and publish them on your changelog.
At UserVitals, we’ve tried to streamline this process as much as possible to make it easier for you, so there’s no more extra work or hassle for you to publish updates for your users.
This is a question we get a lot. Yes, we allow for our changelogs to be on custom subdomains, so all of your changelog entries will be located on their own page on your site.
Try out UserVitals today to find out how product management can work for you.
Tips and tricks for building great products and follow along with our product journey. Subscribe for your backstage access.
