How to write a changelog customers read

Write for the person who was affected

A changelog is for customers, not for the team that built the change. Most readers want to know one thing: does this change affect me, and what do I do now? Start each entry with the situation the reader is in, then the change.

Compare two entries. "Refactored the export pipeline to stream rows" is true and useless to a customer. "Exports of more than 10,000 rows now finish instead of timing out" tells a customer whether to try again. Write the second kind.

Group entries by what changed for users

Group by the user's view of the product, not by the code area. Common groups are "New", "Improved", "Fixed" and "Changed". Some teams add "Removed" when a feature goes away, because that is the group readers scan for when something breaks.

Keep each group short. Three to five entries per release is enough for most small products. If you have twenty, most readers will skip the list, and the one change they needed is lost.

Credit the requests behind each change

A changelog entry that says "thanks to everyone who asked for a monthly export" tells customers their feedback had an effect. That is one of the few ways to show them the loop works. Credit the request, not the person, unless the person agreed to be named.

Keep credit honest. If one customer asked and the change came from your own analysis, say that or leave credit out. Invented credit gets noticed quickly by the people it names.

Link each entry to the feedback it answers

Linking a change to the feedback behind it closes the loop in public. You do not need to publish the feedback itself. A line like "This came from requests about slow exports on large accounts" is enough. Use the internal notes in your inbox to find the original items, and search the text when you do not remember the wording.

Keep a short list of the feedback items each release answers. The list is also your checklist for who to tell, covered in how to tell customers their request shipped.

A changelog entry template

Use the same shape every time so readers learn to scan it. This example is for an imaginary export feature in your own product:

Exports now finish for large accounts. If you exported more than 10,000 rows, the file used to time out. Exports now finish on the first try. Thanks to everyone who reported the timeouts.

The bold line says what changed. The next sentence tells the reader what it means for them. The last sentence credits the feedback, and it is optional when no one asked for the change.

How often to publish

Publish on a rhythm your team can keep. Every two weeks works for many small teams. A monthly post is fine when releases are slow. Publishing once a year is a changelog nobody reads, because by the time it appears, the customer has forgotten the bug.

If nothing shipped, skip the post. An empty changelog entry trains readers to ignore the next one.

Where the changelog lives

Escuta Produto has no built-in changelog. The changelog lives on your own site, in a docs page, or in a monthly email you send from your own address. What Escuta Produto gives you is the input: every item with its status, its notes and its sender, so you know which entries to write and whom to credit.

Choose one place and link to it from your product. A reader who cannot find the changelog will assume you have not shipped anything.

Put the change that matters most first

Most readers see only the top of the page. Put the change that affects the most people first, and mark anything that needs action from the reader. For example, if an older endpoint will stop working on a set date, put that notice above the new features and say what to change. A quiet breaking change buried in the middle of a list is the one that generates support requests.

Avoid long introductions. A single sentence that says what this release is about is enough. Readers who want more will scroll.

Date every release. Readers use the date to judge whether a fix is recent, and an undated list looks like it stopped years ago. Write the entries in the same tense each time and keep the groups in the same order. Readers learn the layout after two or three releases, and a layout that changes every time makes the list harder to scan.

Keeping statuses and the changelog in step

The easiest changelog to write comes from the status workflow. When an item moves to done, it is a candidate for the next entry. Items in progress are not, because nothing has shipped yet. Items closed as a decision not to act stay out.

This makes the status a real signal. Set done only when the change is live for users, not when the code is merged. For the rest of the status workflow, see how to design a feedback status workflow.

If you publish the changelog on a page you control, the hosted feedback page is a good place to point readers who want to suggest the next change. Link them to the place they can ask, and to the changelog they can read.