Why You Should Maintain A Changelog

When you’re building products, there are a lot of best practices recommended to you to make your lives easier, improve your chances of making it, and keeping you, your organisation, or your codebase sane while you’re at it.

One such practice, which often doesn’t make its way into the common best practices list on twitter is “Keep a changelog”.

It is as important early on in your product’s lifecycle as it is when you are a million dollar business

The best time to start your changelog was when you started, the second best time is now

But why? Why should I maintain a changelog?

There is a lot of value in maintaining a changelog, let's list some off the top of our heads

1. Improve customer engagement
2. Increase new feature adoption
3. Build a shipping cadence
4. Build credibility, and gain trust
5. Keep everybody in your company informed

To understand all the value-adds better, let's start with the audience of your changelog or release notes. You’ll primarily have three kinds of people reading your changelog.

1. Your current and future customers
2. Your current and future employees
3. Your investors and your community

Each of these groups of people get value from your changelog in different forms.

Your current and future customers

These are the people who are using your product day in and day out, people who depend on your product for their work day (or fun day).

Remember how excited you feel when Apple does an event where they announce their updates? You listen, and you feel good, right?

Apple follows an annual update cycle. You don’t. You’re not Apple. If you’re a modern software company, you ship updates to your users daily, weekly, monthly, quarterly, or whenever a new thing is ready.

Changelogs keep your customers informed and excited about all the new things you’re shipping to improve their lives. It increases customer engagement, trust, and credibility.

Shipping regularly and fast is an important part of engineering culture at Raycast and our changelog is a testament to that. Existing and new users see that the product is constantly evolving. This is especially important during early stages of the company.

We heavily rely on user feedback from the community and by writing down all bug fixes and improvements in the changelog we show our users that we care about their feedback. Many times we received messages from happy users when they saw that we addressed something that they reported.

Petr, CTO & Co-Founder, Raycast

Your current and future employees

You probably have each team in your company owning a part of your product or responsible for a feature or release. When that team finally ships the feature, it is important for everybody else in the organisation to be aware of what’s new in the product for users.

It is important for them to know because it impacts their work too. This could be one set of engineers knowing what another team in the company has shipped. This could also be the sales or customer facing team knowing what the engineering or product team is shipping to the customers so they could keep their accounts informed or prepare for new support calls and queries.

People who are not part of those teamsm, but will soon be, also like to stay updated with what the company is shipping. It keeps the people you are trying to recruit or people who will apply to your job posts excited about everything you’re shipping.

Inside your product teams it helps build a rallying point for all the development work.

The changelog has been a great way to allow our most passionate customers get regular updates on new features and fixes, they also provide a rallying point for development that keeps us shipping on a regular cadence.

Tom, Founder, Outline

Your investors and your social audience

These people might not interact with your product on a daily basis, or be a part of building it. But they for sure keep an eye on the new things you are building.

Your investors care about your speed of shipping things and direction you’re going in, both of which a changelog solves for.

Your audience on Twitter, LinkedIn, or Facebook care about the new things you’re adding to your product. Maybe the one missing thing that was keeping some of these people on the fence to try your product just launched, your changelog keeps them updated, and will probably bring a lot more engaged customers for the life of your product.

Our public changelog is integrated into the product with a modal that shows whenever we do a large release. This allows us to easily update users about new features and changes without any clutter. The uncluttered way of communicating these updates helps with the adoption of the new features and manages expectations when using the product.

Krijn Rijshouwer, Designer, Framer

Now that we’ve talked about the value a changelog adds to the people who interact with your company or your product, pretty sure you have some questions.

1. We communicate using Slack, Twitter threads, Discord, and Email. Why do we need a separate page for it?
   It as a searchable log of all the changes you've shipped to your product. It does not replace your twitter threads, and all the other mediums you already use, your changelog complements them with more detail. Also, if you're selling to businesses, your changelog helps your case whenever it's time for the annual contract renewal. Plus, it's a place to always go back and refer to what you shipped, and when for you and your customers.
2. We already have a lot where we share the new things we’ve added. Why do we need a separate changelog?
   Your blog is about stories. It should be about stories. You will usually find different kind of content in the changelog and the blog. The changelog or the release note will talk about the new feature that you just shipped and how to try it out, while your blog will talk about the how you solved a very interesting problem in building that feature, or how that feature helped a particular set of your customers, or maybe just talk about why you decided to build the feature. There's no strict rule to it, your stories and your updates can stay on your blog, but it's better to keep them separate in the longer run. 
3. It is another thing to do, who should I get to write these updates?
   Depends on your organisation. It's usually the person whose responsibility it is to get the new release out to production, or someone on the team that built it, or maybe you have a separate product marketing function and it's a product marketer who's writing your release notes. The point is, it's your call. It's always a good idea to have multiple people in your organisation be able to publish things to the changelog.
4. How do I set one up for my company?
   We’ve got you covered. Create your own changelog now 👉