What is a changelog?

A changelog is an information hub where software companies can share any updates made to their product. In other words, it’s a way to document the evolution of a piece of software, so as to provide historical context and keep customers informed of new changes.

Unlike release notes, which are in-depth reviews of functional changes and new features, a changelog usually houses concise updates that can then link out to release notes. Today’s leading technology brands typically adopt this two-pronged approach in an effort to promote transparency and customer support, as well as product adoption.

Why should you have a changelog?

There are a couple of key benefits that come from having a changelog.

For starters, a changelog provides a centralized location to share updates with customers, making it easy for them to quickly identify what has changed in a specific period of time. This means they don’t have to scour through another channel for multiple separate updates. Instead, a changelog ensures that readers can get the full picture after just a few minutes of scrolling through the page, and provides links to more detailed information if the person needs it.

In addition, a changelog helps to show the growth and progression of a brand’s product, giving prospects insight into the level of investment the company has made toward further developing their software. It can also show existing customers how their feedback has been taken into account to change and develop features.

What is the best changelog format?

How a brand structures their changelog depends on how their target audience is used to receiving information. Companies that are just starting to think about a changelog should look at their peers – or the leading platforms their software integrates with – and see how they communicate product changes.

Here are some common best practices:

• As mentioned, changelog posts should be concise, without going into too much technical detail.
• Ideally, each changelog post should include these key details: the date, what the change is, a quick synopsis of the benefits of the change, and the next step for users to take.
• Where relevant, the post can also link to more detailed release notes that explain the more technical considerations behind the update.
• Changelog posts can also include gifs and visuals to clearly indicate where a change has happened in the product, and what it looks like for the user.
• Whatever format a brand chooses, it should be consistent to ensure continuity from one post to another.
• At Intercom, we sort our updates chronologically (from latest to earliest) and categorize them by specific product features, so users can filter the updates based on what’s relevant to them.

For platforms that have multiple products and features, having a filtering option is important. That way, if there’s a customer that only uses one out of five different technologies a brand offers, they can surface the changelog items they’re actually interested in.

All in all, a changelog is a useful tool for software businesses looking to provide clarity around their product evolution, while making it easier for users to find the information they need.