How to write a changelog people actually read
George · 2 min read
The short answer: write each entry from the user's side: what they can do now that they could not before. Lead with the most useful change, add a picture when it helps, group small fixes together, and publish on a steady rhythm. Then share the update where your users are, because almost nobody visits a changelog page on their own.
A changelog is one of the cheapest growth tools a small product has. It shows visitors the product is actively maintained, reminds past users you exist, and gives you something to post when you build in public.
Write in the user's words
Compare:
- "Refactored export pipeline and added CSV serializer."
- "You can now export your invoices as a CSV file, ready for your accountant."
The second one tells a user why they should care. Describe the result, not the implementation. Save technical detail for a short note at the end, if your users are developers.
Lead with the best change
Each update should open with the change that helps the most people. Put small fixes in a short list at the bottom, such as "Fixed a bug where long names were cut off on mobile". People skim; give them the headline first.
Show it
A screenshot or a few seconds of video makes a new feature real. Mark the new part with an arrow or a highlight if the screen is busy.
Pick a rhythm you can keep
Weekly or every two weeks works for most small products. A steady rhythm matters more than size: a short update every week reads as a healthy product, while one big update a year reads as a quiet one. If nothing user-facing shipped, skip that week rather than padding it.
Thank the people who asked
If a user suggested a feature, say so, with their permission. "Thanks to Ana for the idea" turns a feature into a story and shows other users that requests are heard.
Share it where people are
- In the product, with a small "what is new" note for signed-in users.
- By email, to users who opted in, with one or two highlights and a link.
- On social media, as a short post with the picture.
- On your launch page, if the site lets you post updates or answer comments, so visitors see the product is moving.
The short version
- Write what users can do now, not what you refactored.
- Open with the best change and group small fixes.
- Add a picture for anything visual.
- Keep a steady rhythm.
- Share each update where your users already are.