How to write a changelog people actually read

A changelog is the public record of what you’ve shipped. For most products it’s also one of the least-read pages on the site: a long list of version numbers and terse lines like “Improved performance” that nobody outside the team understands.

It doesn’t have to be. A good changelog shows customers the product is moving, helps them discover what’s new, and tells the people who asked for something that it’s done. This guide covers what to include, how to write each entry, and how to get it in front of the right people.

Who reads a changelog

Write for the people who actually come to it:

• Customers checking whether something they need has arrived.
• Prospects judging whether the product is alive and improving.
• Your own team, especially support and sales, who need to know what changed before customers ask.

None of them want a commit log. They want to know what they can do now that they couldn’t before.

What to include

Not every change deserves an entry. Include:

• New features customers can use.
• Meaningful improvements to existing features: faster, simpler, more flexible.
• Fixes customers noticed. Especially ones they reported.
• Changes in behaviour that could surprise someone, such as a moved setting or a new default.

Leave out internal refactors, dependency updates and minor fixes nobody would notice, unless they change something visible.

How to write an entry

Each entry should answer three questions: what changed, who it’s for, and how to use it.

Lead with the benefit

Compare:

• “Added CSV export to the reports module.”
• “Export any report to CSV. Open a report, choose Export, and open the file in Excel or Google Sheets.”

The second tells the reader what they can now do and how. Start with the outcome, then the detail.

Use the customer’s words

If customers asked for “a way to get my data into Excel”, say that, not the internal name of the feature. People scan for the words they would use.

Keep it short

A title and two or three sentences is enough for most entries. Link to documentation for anything that needs more.

Show it

A screenshot or a short animation makes an entry far easier to understand than a paragraph. One image per significant entry is plenty.

Credit the request

“Many of you asked for this” or a link to the original request tells customers that feedback leads somewhere, and that’s the strongest reason to keep giving it.

Structure the page

• Newest first. Readers want what’s new.
• A date on every entry. It shows activity at a glance.
• Group small items. A weekly or monthly entry with several small improvements is easier to read than many tiny ones.
• Optional labels. “New”, “Improved”, “Fixed” help people scan.

How often to publish

Consistency matters more than frequency. Pick a rhythm you can keep, weekly, every two weeks or monthly, and publish on it even when the list is short. A changelog with a recent date says the product is alive; one that stopped months ago says the opposite.

For big launches, publish a separate entry when they ship rather than waiting for the next roundup.

Get it in front of people

A changelog page nobody visits is a diary. Bring the news to readers:

• Notify the people who asked. The customers who requested or voted for a feature should hear about it directly. It’s the most valuable message you can send them. Our guide on closing the feedback loop covers this.
• Link it from the product. A “What’s new” link in your app’s menu or help panel reaches active users where they are.
• Share it with your team first. Support and sales should know before customers ask.
• Link it from your roadmap. Items that move to Done can point to their changelog entry.

Use AI carefully

Drafting entries from a list of shipped work is a good use of AI: it turns terse internal notes into readable text quickly. But review every draft. Check that it describes what actually shipped, uses your customers’ words, and doesn’t promise more than the feature does. A wrong changelog entry creates support tickets.

A template

For each entry:

1. Title: what customers can now do, in their words.
2. One or two sentences: who it’s for and why it helps.
3. How to use it: where to find it, in one line.
4. An image, if it’s visual.
5. A link to docs or to the original request.

Before and after

Here’s a typical internal note turned into an entry customers read.

Internal note: “Reports: add CSV export endpoint, button in toolbar, fix encoding for non-Latin characters.”

Changelog entry:

Export any report to CSV

Open a report and choose Export to download it as a CSV file you can open in Excel or Google Sheets. Names and comments in any alphabet now export correctly too. Many of you asked for this; thank you.

The entry leads with what the reader can do, says where to find it, mentions the fix customers would notice, and credits the request. The endpoint is an implementation detail; it stays out.

Keep a changelog and release notes in step

Some products have both a changelog and more detailed release notes or documentation. That’s fine, as long as they agree. Let the changelog be the short, readable summary that links to the detail, and update both at the same time.

Common mistakes

• Writing for engineers. Version numbers and ticket IDs mean nothing to customers.
• Vague entries. “Various improvements” tells nobody anything.
• Irregular publishing. Long gaps make the product look abandoned.
• Announcing only on the page. The people who asked never see it.
• Overselling. Describe what shipped, not what you hope it becomes.

How AntNexo helps

AntNexo’s changelog is connected to your feedback. Pick the initiatives that shipped and the AI drafts an entry announcing them, which you review and publish. Customers who signed in and posted, voted or commented on the posts behind it get an email in their language, and the entry appears on your public changelog page next to the roadmap.

See how the changelog works, how it connects to the public roadmap, or what changes for product managers.