PM Basics: How to Get Changelogs Right

From your customers to your devs, and from your business unit to product team – changelogs are the single resource that help everyone keep track of your brand, and how you solve problems.

Often misunderstood and therefore overlooked, changelogs do not get the credit they deserve. In this blog, you will learn why you need to solidify processes for keeping changelogs. We will also delve into how to craft these perfectly, and a killer distribution plan to make all your effort worth it.

Why you need Changelogs

1. Changelogs keep everyone in the loop

In a diverse and vast team, everyone is focused on their tasks which have a meaningful impact on the bigger picture. However, losing track of the bigger picture is fairly easy amidst the everyday. 

Changelogs serve as a repository of all the changes that have been made to the product. Your dev team can infer the state of the codebase, changes and merges, and more from this timely update. Business facing teams can arm themselves with the right collateral and set to help out customers and prospects. 

Your users can see how you take action on their feedback, and involve them in the growth of your product. This makes them feel heard and valued.

2. Changelogs help drive adoption of your features

Your champion users are the ones who have a lot of faith in you. They’re keen on seeing how you’re working to make their lives easier, and are definitely going to check out anything new you’re putting out.

Further, all users are hacking away at some problem or the other. By letting them know what’s improved, new and faster solutions to existing problems, you can get them to explore more of your product. This helps you drive adoption of your new features, but also helps engage your users over time.

3. Changelogs make you look trustworthy

If everything is branding and marketing, think about how the public perceives a well-composed changelog. When you offer visibility into what teams do, how the product is evolving, and acknowledge bug fixes, the audience will respect your transparency and honesty.

Over a longer period of time, your changelogs clearly reflect the evolution of your product. This shows new users where you started, how far you’ve come, and how far your zeal and commitment will take you.

4. Changelogs set up your shipping cadence

When you’ve got a cadence in place that you must share release notes every month, you’ve got a team that is looking forward to it. Your dev team knows and feels personally responsible for shipping things on time.

With the process in place, your business teams know how to take action on everything new and useful for the users. This way, the entire organization gets in order, and knows the next steps they need to take without needing inputs or guidelines every few weeks.

How do I format my Changelogs?

When you know how important changelogs are, you obviously want to get started right away. But it is imperative to take a step back and access – what even should go into your changelogs?

You could use the format that your favourite tech companies use, but chances are they put a lot of thought behind them to make them suit their use cases. So let’s look at how you can define your use case, and get them right.

1. Defining Use Cases

The key here is to look at your entire possible audience, and understand how they benefit from the changelogs.

• Users/Customers: This segment benefits from knowing what’s new and will help them get their jobs done faster, what was broken that has been fixed, and also how to adapt to these changes without any friction.
• Support Team: The support team needs all key information that users do, so they can assist customers navigate through your product faster. The support team should also have access to internal documentation for more clarity, whenever needed.
• Community & Followers: Creating buzz around major launches will get this segment excited, helping you market organically, drive product adoption, and get new customers by spreading the word.
• Investors: Investors are looking to see growth, and improvements in the product quality have a massive impact on how well a product is received in the market.

You can skip anyone who wouldn’t directly benefit from receiving these. For example, a good practice is to publish your changelogs on your website.

2. Writing the changelog

When you start writing the actual changelog, get the basics done right away. This includes:

• Release date
• Release version
• Description (what’s new and what’s fixed)

Further, it is highly recommended that you categorize your changelogs. Knowing what your audience wants helps you create the right categories. 

A few categories to get you started here would be:

• New
• Changed
• Deprecated/Removed
• Fixed
• Privacy & Security

This can be used as a label on the elements of your changelogs, and it also helps you structure the changelogs for scanability.

How do I effectively distribute my Changelogs?

In Marketing, we say – distribution is everything! After all of the time and effort spent getting your release notes just right, you have to make sure they reach everyone who has any use of them.

For this, the audience that you defined in the previous section will be really helpful. These are all the folks who will benefit from these changelogs. So essentially, you simply need to target them with your changelogs.

Try to put a simple distribution framework in place for all segments who should receive your changelogs. Here’s how to get started.

1. Updates for all users

Users are accustomed to hearing from your customer success team and support functions. Bring them closer to you with a personalized email update that gives them all the highlights in a glanceable format. You can also have your Product Team participate in this as this helps bring the users and the product closer.

A lesser known but effective technique is to also share these on the product itself, as this helps drive engagement on the platform, and opens up multiple touchpoints that you can explore in the future.

2. Internal share for your org

We’ve already counted the benefits of sharing changelogs with the whole team. Sharing these release updates on the internal communications platform, such as Slack, means everyone gets the update and they can go back and refer to it whenever they need to.

3. Publishing for public viewing

Keeping a public repository is super helpful. You can host it on your website, set up a publication on Medium or Substack, or have a dedicated portal for your changelogs.

‍

And yes, you’re on the money – the distribution is a time consuming process if you don’t plan it properly and automate it as you go. But you can offload this laborious process to Zeda.io, where release notes and changelogs are captured and distributed smoothly.

You can trigger automated changelog emails to segmented users, use integrations to send them on Slack channels and more, and even publish them on your customer portal where they’re available for public viewing. 

At Zeda.io, we build for users. We value feedback over everything else and ensure that we bridge the gap between your product and users in every way. The automation, and saved resources are great added benefits, but the real charm is in how the quality of product development skyrockets in this process.

How often should I publish fresh changelogs?

Changelogs work short-term & long-term, serving many purposes and simplifying much of what makes for ‘quick syncs’ and misinformation. You might find that your team benefits from getting this information once a week, while users might get annoyed with the weekly updates, and benefit from only seeing these once a month.

The industry best practice is to publish the changelogs for users and customers once a month. But really, the trick is to hear your users and offer them what they need. This means it’s absolutely okay to change the frequency if data suggests you can do it more often or less often.

All the features you build are intended to solve your users’ problems. Similarly, the way to think of changelogs is that they serve as a key touchpoint that gets users in-tune with the latest, fastest way you’ve hacked to make their lives a little bit easier.