Changelogs can be one of the most important parts of a company. Here’s why your startup needs one, and how you can implement your changelog with UserVitals for best results.

What’s A Changelog?

Simply put, changelogs are a chronological record of all changes made to your product, including bug fixes, feature changes and updates. This is often made publicly available to boost the product’s transparency and keep customers informed on updates and bug fixes.

Benefits

There are many benefits to creating a changelog. For one, as previously mentioned, it helps boost transparency between your developers and your customers or clients. Clients now know what changes are being made to the product, and thus become more knowledgeable about the product they’re using.

This transparency in turn boosts communication between your team and your customers, who may feel more included in your development and thus satisfied with the product itself. This is especially important with startups, whose first customers can often be the most eager and willing to be involved in the process.

Likewise, having a changelog can also help boost feedback from our customers. Because they’re now more in the loop with changes, they can help give you feedback on what changes have worked and what may still need to be made.

Changelogs also have benefits for the developers themselves. As changelogs are essentially records of all issue changes, product updates and bug fixes made, they can serve as a way to boost momentum by reminding developers of all the progress already made as well as the progress to come.

How to Setup a Changelog

Setting up a changelog is easy. We’ll go through how to format it, our best tips and tricks, and some popular examples to help guide you.

Format

Good news: changelogs often don’t have a strict format to follow. But there are a few guidelines that are important to follow.

First of all, changelogs are always in chronological order and are often organized by update or issue. This is simply for organization and readability, allowing customers and developers alike to skim for the information they’re looking for. Likewise, all updates should have a release date attached to them for easy reference.

Secondly, each issue should be visually formatted to make it easy on the eyes. This may include using headings, subheadings and bullet points for each issue, and possibly the use of italics and bold-type as well.

Simply put, your changelog needs to be reader friendly. Large blocks of text can often be off-putting to the reader. Keep sentences short and break up your text to prevent this.

Tips

Now that we’ve discussed the proper formatting and technical details for changelogs, let’s talk about some of the best tips for making your changelogs even more effective.

First and foremost, every software version or update needs to have an entry, even if the updates themselves are small. Like we mentioned early, headings and subheadings can be any easy way to help break up your text appropriately.

Another easy way to do this is to add sufficient white space to your changelog. This can simply be text breaks, or you could also include images as well. Furthermore, if you’re worried about losing reader interest, you could also add a summary section to each version update to quickly review all the changes mentioned.

Above all, it’s crucial to keep in mind that you’re writing your changelog for real people to read, not machines. While some familiarity with software development terms can be expected, you’ll need to make sure all updates are readable and can be understood by your average customer.

Examples of Great Changelogs

Now that you know what you need to create your changelog, let’s go over some examples of great ones to give you an idea of what you want to model.

If you want another sample changelog template to base yours off of, check out GitHub’s.

Intercom

Intercom’s changelog is clean, simple and very readable. They also have a great “What’s New” summary section that allows readers to easily skim through new updates and find what they’re looking for, as well as links to longer sections and more detail.

Furthermore, they also have social capabilities built into their changelog. Readers can react to different updates, giving developers a better understanding of what their users like and dislike.

Slack

Slack’s changelog is great because it is chronological, utilizes a lot of white space and is easy to read. While it keeps updates short on the changelog itself, it includes “learn more” links to longer explanations of each update. 

Its organization and structure are also very visually appealing. While they break up their changelogs by heading based on the month, they also have labels on individual releases that tell you what feature they’re talking about (e.g. the app, APIs, etc.).

GitHub

GitHub’s changelog is a little different from the other two. While the others have a specific changelog list, GitHub’s changelog exists in their blog—each item links to a specific blog post that details the updates made.

These blog posts are generally pretty short, and include images and graphics to help explain. But they also include links to more information if readers want to know more.

Creating a Changelog with UserVitals

Creating your changelog with UserVitals is easy and pain-free.

Our changelog functions like our feedback widget and can be added to any website or triggered by the click of a button, allowing customers to easily view product releases and updates without leaving the site. We work a lot like AnnounceKit, Beamer and Headway, but much simpler. 

We also allow for custom subdomains for our changelogs, meaning all of your entries and updates will be available on their own page on your site. 

In our app, head to the Changelog tab in the sidebar. This is where all of your changelog entries will appear, formatted by date and type.

‍

To add a new entry, click on the New Draft button in the top-right corner of the screen. Add a title for your changelog entry, and then head to the next screen.

From here, you can add a description and hero image. Our descriptions allow for many different types of text formatting, such as markup, links, highlights and even headings. For further organization, you can also add a custom label and entry type.

‍

Once you’ve finished filling out your entry, click Publish (or Save if you’d like to keep this as a draft), and it will automatically be added to your changelog. You can add as many entries as you want when you want, or when a new update is released.

Find out more information on how UserVitals can help you connect with your customers and keep them informed, and join our product demo today.