Most changelogs are written for the wrong reader. They are written for the team that shipped the work: precise, exhaustive, and organized by pull request. The customer who opens one is asking a much simpler question: what changed for me, and do I need to care?
Last year we rebuilt the Lagoon changelog around that question. Readership went from a rounding error to our second most visited page, ahead of pricing. Support tickets started quoting entries back to us. Nothing about the product itself changed. Only the writing and the pipeline did. Here is what we learned.
Write the change, not the commit
The commit message says what happened to the code. The changelog entry says what happened to the reader. Refactored ingestion worker for multi-source dedup is a commit. Duplicate feedback from Slack and email now merges automatically is an entry. Same work, different sentence, and only one of them earns a click.
The test we apply is simple: could a customer read the entry aloud to a colleague and have it make sense without any additional context? If the answer is no, the entry is not translated yet. Translation is the job. It usually takes five minutes and it is the five minutes that decide whether the page gets read.
The three-line format
Every entry in our changelog follows the same skeleton, and the predictability is the point:
- What changed, in one sentence a customer would actually say out loud.
- Why it matters, phrased around a task the reader already does every week.
- What to do next, even when the answer is nothing, it is already live for you.
Readers learn the rhythm within two visits. They can scan twenty entries in a minute and stop only where their own workflow shows up. That scanning behavior is not a failure of attention. It is the feature.
If a reader cannot tell what to do differently after an entry, the entry is not finished.
Small entries beat big roundups
We used to save announcements for a monthly digest, on the theory that bundling made the product feel bigger. In practice it made every change feel late. A fix that lands on Tuesday and gets announced three weeks later reads like an afterthought. Now an entry ships the day the change does, however small. Momentum, it turns out, is communicated in frequency, not volume.
Treat the changelog as a build artifact
The writing discipline only stuck once we made the changelog part of the codebase instead of a marketing chore that lived in someone’s drafts folder.
Entries are Markdown files that live in the repository, right next to the code they describe. They are written by the engineer who built the change, edited in review like any other file, and published automatically on merge. A customer-facing pull request without an entry fails the checklist, the same way missing tests would.
This does three quiet but important things. It removes the handoff, so nothing waits on a second team’s calendar. It keeps the author honest, because the person who knows the caveats writes the sentence. And it gives the entry a reviewer, so tone and clarity get the same scrutiny as logic.
Let the reader subscribe their way
The page is the canonical record, but almost nobody refreshes a page. We publish the same entries to an RSS feed, a Slack digest for connected workspaces, and a short monthly email for everyone else. One source, many surfaces. The entry is written once and never rewritten per channel, which is the only way the habit survives a busy quarter.
What changed for us
The surprising part was not the traffic. It was who the page started working for. Sales sends changelog links in follow-ups because the page proves the product is alive. Support resolves how do I tickets by linking the entry that introduced the feature. Renewal conversations open with a scroll through what shipped since the last contract, which is a much stronger opening than a slide deck.
A changelog people read is not a writing talent problem. It is a decision about who the page is for, plus a pipeline that makes the right behavior the default. Decide for the reader, wire it into the build, and the readership follows.