How to write a changelog people actually read (with a template)
By Naod Tadele · · 5 min read
Most changelogs are written for the person who made the change. They list commit messages, ticket numbers and refactors. Then the team wonders why nobody reads them.
A good changelog is written for the person who uses the product. It answers one question: what's different for me now? Here's how to write one that people open, read and share.
Who reads a changelog
Before you write, know your readers. There are usually three:
- Current users who want to know if the thing that annoyed them is fixed.
- People evaluating you who check the changelog to see if the product is alive and moving.
- Your own team looking for when something changed.
The first two matter most, and neither of them cares about your internal names for things. Write for them.
Rule 1: Lead with the change, not the work
Compare these two entries:
Refactored export pipeline to use streaming writer
Exports of large projects no longer time out. You can now export any size.
The first one is true. The second one is useful. Same work, different reader.
A simple test: could a user who has never seen your code understand the line? If not, rewrite it.
Rule 2: Group by what people care about
A flat list of twenty items is hard to scan. Group entries so readers can skip to what matters to them. A common split:
- New: things you can do now that you couldn't before.
- Improved: things that work better or faster.
- Fixed: bugs that are gone.
Put the most important item first in each group. If one change is clearly the headline, give it its own short paragraph at the top.
Rule 3: Skip what nobody notices
Dependency bumps, internal refactors, test changes and CI tweaks don't belong in a user changelog. If a user can't see or feel the change, leave it out. Keep a technical log somewhere else if your team needs one.
The exception is anything that affects behavior: breaking changes, removed options, new limits. Those always go in, near the top, in plain words.
Rule 4: Show, don't describe
One screenshot or short clip of a new feature beats a paragraph about it. For anything visual, add an image. For anything technical, add a tiny example: the new config line, the new command, the new API field.
Rule 5: Date it and ship it often
Every entry needs a date. A changelog with recent dates tells evaluators the product is active. A changelog last updated months ago tells them the opposite, even if you've been shipping.
Small, frequent entries are easier to write and easier to read than one giant update every quarter. Weekly or per release both work. Pick one and keep it.
A template you can copy
## [Date] [Short headline for the biggest change]
[One or two sentences on the main change and why it matters to the user.]
### New
- [What you can do now, in user words]
### Improved
- [What works better, and how they'll notice]
### Fixed
- [The bug, described the way a user would report it]An example entry
Here's what that looks like for the fictional product Nightshift, which writes incident summaries for on-call engineers.
Oct 27: Summaries now land in Slack When an incident closes, Nightshift posts the summary to the channel you pick. No more copying it from the dashboard. New: choose a Slack channel per service Improved: summaries for incidents over 6 hours now load in under 2 seconds Fixed: timestamps showed UTC even when your team used local time
Notice what's missing: no ticket numbers, no "refactored", no "various improvements".
Turn your changelog into posts
Your changelog is the easiest content source you have. Every entry is a small story: a problem someone had and how you fixed it. Each one can become a post on X:
Nightshift used to make you copy incident summaries into Slack by hand. As of today it posts them for you, to the channel you choose. Small change. Probably saves every on-call engineer a few minutes a night.
The headline change becomes a launch-style post. The fixes become short "this annoyed people, now it doesn't" posts. The improvements become before and after posts. One changelog entry can fill a few days of posting. For more on this, read how to turn GitHub commits into posts people actually read.
Common mistakes
- Pasting commit messages. They're written for developers in the middle of the work, not for users.
- "Bug fixes and improvements." It says nothing. Name at least the one fix people asked for.
- Hiding breaking changes. Put them first. Users forgive change. They don't forgive surprises.
- Updating only for big releases. Long gaps make the product look quiet.
How Loudcode helps
Loudcode reads your GitHub commits, pull requests and releases and turns them into draft posts for X in your voice, so the work you already described in your changelog doesn't stop at the changelog page. On visual posts it can add a screenshot of your live app. You review and edit every draft, and nothing posts without your approval.