The subtle art of the changelog

In some ways, changelogs are the precursors of the “build in public” movement. Or rather, the foundation. They’re an effective tool for communicating progress and tracking bug fixes, feature updates, and other changes you’re making to your product for your users and customers.

Yet, oftentimes they end up being a missed opportunity to signal the exciting things happening with your product.

Let’s look at why keeping a great changelog is important for your brand and in helping you to engage and activate your most powerful users.

A brief history of the changelog

Pinpointing when and where changelogs started is difficult. The earliest record of a changelog likely happened sometime in the late 1970s, when software developers began to document changes made to their programs. It was also when commercial software was available to the average customer, so the need for a chronological list of updates and fixes was greater.

The concept of a changelog has evolved over time, and the format and content of these documents have changed significantly since the earliest versions were published.

Many of these weren’t official documents published on a company’s website, but rather informal notes made by the developers.

Many weren’t called “changelogs” either. Before the Dot-com bubble, you’d be more likely to see these types of documents regarded as “news,” or later, release notes. It is believed that the term “changelog” originated in the open-source software community where it was meant to describe a log of changes made to a software project.

To give you an idea of what an old-school changelog looked like, you’d often find them as stand-alone multi-page documents.

Sometimes, they’d be part of the user manual that came with a new release. Microsoft’s Windows 95 added a What’s new? page to its 1995 operating system manual, highlighting a summary of the improvements they made and noting that the full log of changes can be found in the Help Index.

Changelogs would also be part of the launcher: the first window that would pop up when you’d open a piece of software for the first time after an update. You’d then be able to access it at a later time within the product.

Fast-forward to the early 2000s, as SaaS companies began to emerge and gain popularity, the importance of changelogs increased. These companies needed a way to efficiently communicate updates and changes to their software to their customers.

Examples like Microsoft’s version of the changelog from the late 90s also emphasize the shift that happened in software development through the consumerization of enterprise tech. Products went from having annual or semi-annual releases to continuously shipping new features, which we like to call quicksand software.

To address the need for frequent updates, many SaaS companies adopted automated changelog systems like GitHub's Releases. Systems like these enabled developers to easily generate and share comprehensive changelogs with customers on a regular basis.

Changelogs in the wild

Simply keeping a changelog does not mean your job is done. Many companies underestimate the importance of writing great release notes, using the same generic message each time they update them. It’s usually something along the lines of “We regularly ship improvements” or “We’ve crushed bugs and made improvements.”

Others have mastered the art of the changelog, taking advantage of this additional channel and using it to express their brand voice, inject some personality, and stand out in a sea of lazy, low-effort changelogs.

Companies like Slack have turned their changelogs into a form of marketing, by highlighting the most significant changes in a catchy, humorous, and witty way. They even go as far as poking fun at those generic messages.

Citymapper has been doing a great job at writing fun changelogs for a long time. While its latest one (and last of 2022) quotes “See you all next year, have fun, take care, be nice…,” they were far ahead of the release notes game even back in 2013. By taking an otherwise tedious task seriously, they turned what could be seen as an annoying bug into an opportunity to enforce their laid-back brand voice. Then there was this cheeky Apple keynote satire that topped it off.

Medium used to keep an archive of its Friends episode titles inspired changelogs: “The one where we didn’t say bug fixes” and “The one with the back-to-school enhancements.” to name a few. Unlike Citymapper, which is still regularly updating its witty changelog archive, Medium’s seems to have stalled in late 2019. Consistency is important, folks.

If you want to get more inspiration, there’s a Tumblr for that. Keep in mind that funny changelogs can sometimes be too much of a good thing, so finding a balance between humor and value-adding information is in fact an art.

Should your company write a changelog?

The short answer: probably, yes.

It’s not so much about the type of company (i.e. SaaS versus consumer social) as it is about what the company prioritizes.

Your team should actively invest in writing a changelog if:

• You want to build trust and demonstrate transparency and accountability by openly sharing the changes you have made to your products.
• You run an open-source project. Many of these use changelogs as a way to acknowledge and credit the contributions of the community by listing the names of the contributors alongside the changes they made.
• Precision and accuracy are important to you and your users. This includes analytics apps, finance apps, or any other tools that handle sensitive data.
• You want to create a strong community of supporters. Sending regular updates gives your power users a dopamine fix, making them feel included and giving them a sense of belonging. Changelogs are a great way to engage with early adopters who can later become advocates.
• You’re an early-stage startup. Especially if you’re fundraising. Keeping an active changelog shows your company’s ability to execute and make progress fast. Depending on whether you allow responses from your users and customers, it can also validate the value your product provides.
• You’re actively recruiting. In some ways, potential employees are just like potential investors. By including a changelog on your website, people who are interested in joining your company can get a better sense of how you approach product development and what you care about most — for startups, this should usually be a bias for action mixed with enough attention to detail.

How to write great changelogs

Humorous changelogs are great, but without being informative, they can quickly become silly. There’s no recipe for success — experimenting with different changelog styles is the best way to find your brand’s voice.

Here are a few of our recommendations that can be applied independently of what your product does.

Know your audience

Is the changelog intended for end users/consumers? Then you should make it as digestible as possible and focus on the value the change brings to them. But if it’s developers you’re addressing, focus on the technical details. They won’t care as much if your brand colors have changed, but they will care if you’ve removed or added certain functionalities.

Organize the changelog

As much as you’re proud of all the things your team has shipped, you don’t need to add all the small changes to the changelog, especially if they don’t directly affect the user (think backend changes with no impact on the visible user experience). Ensure you organize the changelog by release, with the most recent changes listed first. Within each release, list changes in order of importance, with the most significant changes listed first.

Using headings and bullet points to break up the changelog can also make it easier to read.

Visuals are key

Consider adding screenshots, mockups, or GIFs that exemplify the new features or bug fixes. Before and afters also work great at showing progress.

Keep it short

Keep the marketing spiel for the blog, or remove it altogether if it doesn’t add value. Put yourself in the shoes of the user and focus on them walking away from an update more informed and excited about your product. Short, sweet, and to the point.

Have a clear CTA

What do you want users to do once they’ve read the updates? In some cases, this might be updating to the latest version, while in others it’s checking out the website and reaching out with feedback.

Anticipate the questions

Is there anything you haven’t covered that can be answered by checking out different areas of your product? Make sure to link to them, whether that’s more detailed documentation or FAQs.

And lastly… be consistent.

How will people stay up to date?

It’s worth considering how your end-users will keep updated with new changelog entries. After all, what’s the point of meticulously maintaining a changelog if no one ever reads it?

Adding a link to your changelog from your homepage is a good idea, but it relies on users remembering to go back to your changelog regularly to look for updates. Emailing users is better, but most emails don’t get read, and social posts are only seen by those around when they’re posted. Instead, consider a dedicated changelog service.

At first, you may wonder why you need yet more software if you already have a blog platform. But the real value of dedicated changelog services (like Headway or Beamer) is in the range of notification options they provide. Some enable users to subscribe and get emails about all new submissions, whereas others give you the option of flagging new additions in-app - either as a banner, popup, or some other form factor.

Going beyond the changelog, it’s increasingly common to see SaaS organizations take a leaf from Apple’s marketing playbook and run regular product announcement events, like New at Intercom or Stripe’s Sessions. Software may now be continuously delivered, but that can prove to be problematic for clear messaging that cuts through the noise. There’s something to be said for a regular cadence of big bang product launches to get everyone’s attention. You can then use your changelog to keep that momentum going until the next flashy show-and-tell.

When changelogs go wrong

Plenty of companies fall into the trap of following what others are doing without putting much thought into it. Just like adding dark mode to your product won’t solve all your problems, creating a changelog doesn’t automatically mean your users will know about your latest releases. A performative changelog adds to our workload but doesn’t add much in the way of value creation.

Several factors can make a changelog "bad" or ineffective:

• The audience is not taken into account. Your voice should change depending on who your user is. Building a banking app? Cut down on the jokes and focus on the facts. Building a social app for Gen Z? Wit can go a long way.
• Using too much technical jargon for regular users to understand what’s new and how those changes benefit them.
• Not giving enough detail. Avoid being so vague that the user doesn’t find any value in reading your changelog. “We fixed bugs” versus “We fixed the bug preventing you from uploading new documents” is a good example of how a few extra words can give a lot of additional, useful information to the user.
• TLDR! Not even your most active user will read a 3-page long PDF outlining all the changes you’ve made to your codebase. If there’s anything we can learn from SaaS going from semi-annual releases to continuous ones, is that there’s always a next changelog.

A changelog can be a great asset if you use it wisely. Its contents and how you distribute it for others to see matter a lot more than whether you’re using your blog, a GitHub repository, a dedicated service to do it, or if you’re following a certain structure.

In the words of a very passionate changelog advocate, go and Keep a Changelog.