What makes a good changelog?

There are tons of tools to auto-generate changelogs, but when everything’s automated, you lose the human touch. 

A good changelog is more than a sterile list of updates — it’s a direct line of communication with the people using your product. 

Read on to learn more about: 

• What a changelog is, and why it’s important
• Critical components of a good changelog
• Best practices for creating an effective changelog
• How WorkOS applies these Best practices 

What is a changelog, and why is it important?

A changelog is essentially a record of updates, showing everything that’s changed in a product over time — new features, fixes, and security patches. Consider it a running log with the latest updates at the top.

Changelogs are essential communication tools.

When users see a changelog, they can get a clear sense of what’s happening with the product — what issues have been fixed, what new features they can try, or even if there’s anything still being worked on.

It’s especially handy for developers because it helps track versions and ensures everyone knows what’s compatible and up-to-date. But overall, it’s a great tool for transparency and helps people feel more connected to the product as it grows and changes.

What makes for a good changelog?

Critical components of an effective changelog include:

• Clarity: Each entry should be accessible and easily understood without jargon or filler. Users should immediately grasp what has changed and why it matters.
• Relevance: Include only necessary details that add value to the user’s understanding. Avoid vague statements; instead, provide specific information that addresses the changes.
• Organization: Structure updates in a logical, readable format. List entries in reverse chronological order and group updates as features, bug fixes, improvements, etc., for quick reference and readability. 
• Concision: Avoid lengthy descriptions. Summarize each update in a way that gets the point across quickly. 
• Link-ability: Make each update entry linkable. This way, users can directly reference specific updates in support tickets, discussions, or documentation.

5 changelog best practices

Here are five best practices to follow to make the best changelog:

1. Changelogs need to be clear

A changelog isn’t a place to sell. The content must be essential, straightforward, and clear. If you have fluff in your changelog, you're doing it wrong.

Even if you think you can make someone laugh, it’s not easy, and that’s not the point. It’s generally much better to put effort into being clear in your content than selling or being funny.

(And please, no more “Bug Fixes and Improvements!”)

For example, when WorkOS added session management for frontend apps, the changelog read, “Developers can now integrate sessions into public clients, like mobile or single-page apps. Use our React or JavaScript SDKs to make sure that your users’ sessions are secure by default.”

Clear and direct.

Related read: WorkOS technical content style guide.

2. Highlight changes using images

As software engineers, we spend a lot of time in our text-based apps, such as code editors and terminals, so it’s easy to overlook the importance of images.

To make your entry stand out, focus on highlighting its main point. Incorporating images can make the content more engaging, as visuals naturally resonate with readers.

But simply including a screenshot doesn’t clearly show what you specifically changed.

You have this vast product, and you're talking about this little thing that changed. You need to show the reader what to pay attention to. When composing an image, you must draw attention to what exactly changed. 

There are many different ways you can do this. For example, you can annotate it with a red box or circle.

3. Spotlight the people behind the product

It’s easy for a company to show only what it shipped. This impersonal viewpoint is understandable if it comes from Apple or Google.

But if you don’t work for these big companies, there's nothing wrong with being transparent.

It’s good to show the people who contributed to each change for two reasons: 

1. If I’m external to the company, it’s nice to see real people with whom I can connect and talk. If I see their avatars on the changelog, I can recognize them on Twitter or another social media site. This helps build trust and familiarity.
2. Publicly acknowledging the contributors provides a greater sense of ownership to the engineers on the team. They have their names and avatars as creators of the feature. 

There’s nuance to this, though: I’ve noticed that this motivates some people but does not affect others.

4. Formatting versions and dates

The date is a crucialdetail of any changelog. Include clear and accessible date formatting to avoid ambiguity, especially for a global audience (e.g., "August 11, 2021" instead of "11/08/2021").

It’s also important to note the versions. If you're building a library, framework, or SDK, the version is more important than the date. For those cases, you should always rely on semantic versioning. 

5. Changelogs need engineering time

Usually, a startup would want to avoid putting as much responsibility on the engineers as possible. But it’s essential to have engineers write the entries for the changelog. 

A changelog is an extension of your product and influences the product’s usability the same way docs, SDKs, and demos would. It needs to feel like it was made for your product. If it’s driven by the engineers who built the product, then naturally, that process becomes more manageable.

Even if you don’t think your changelog will have many external readers soon, it can still be helpful for your colleagues in the support team or the marketing team. It can serve as a communication tool from your engineering team to the other departments.

How WorkOS structures changelogs effectively

At WorkOS, we decided to create our changelog as a part of our website instead of relying on automatic generators. Launching the changelog was simple, but the magic is in the details.

Here are some of the best decisions we made to make our changelog the best we could:

• Detailed but concise descriptions: Each entry is clear and consistent, specifying precisely what was updated and how it impacts users.
• Highlighting contributors: Each entry showcases the team members behind the updates. 
• Using images: To draw attention to what changed in images, WorkOS creates a subtract effect, where you keep everything around your image more grayish. The changed piece remains normal (like this!), which stands out from the grey background. ‍
• Dates: WorkOS spells out the month instead of just using numbers. So, for example, instead of 11.08.2021, we write August 11, 2021. (Otherwise, the reader could think we meant November 8, 2021.)

• Linkable entries: Each WorkOS entry is linkable, so readers can easily share and reference specific updates.
• Reverse chronological order: Entries are listed with the most recent updates at the top, so readers can easily access the latest information.

If you ever want to learn what to expect from WorkOS, read the WorkOS changelog.