How to Write a Changelog People Actually Read
A changelog is the cheapest trust signal a software product can publish, and most are unreadable. Structure, voice, and what to leave out.
Published 2026-11-13 · 4 min read
Across the products in our directory, 12.2% publish a changelog while 45.5% run a blog. That inversion is strange: a changelog is easier to write, more useful to a buyer, and rarer — which means publishing one puts a product in a small minority of its category.
Why almost nobody reads a changelog — and why that is fine
Changelogs are not written to be read in full. They are scanned for one thing: evidence that this product is still being worked on. A buyer evaluating an AI tool where models, APIs and pricing shift constantly is mostly asking whether it will still exist and still work in six months.
That question is answered by dates and cadence, not by prose. Which means the format matters more than the writing.
The structure
| Element | Rule |
|---|---|
| Date | Every entry, ISO or unambiguous ("12 Nov 2026", not "11/12"). The date is the signal |
| Version or release name | Optional, but consistent if used. Do not mix schemes |
| One line per change | What changed, for the user. Not what you refactored |
| Grouping | Added / Changed / Fixed, in that order. Only include a group if it has entries |
| Breaking changes | Flagged at the top, with what to do about them |
| Links | To docs or the affected screen, where useful. Not to every ticket |
Writing entries that mean something
The difference between a useful entry and a useless one is whether it says what changed for the person reading:
| Useless | Useful |
|---|---|
| "Bug fixes and improvements" | "Fixed: exports failed silently when a filename contained a comma" |
| "Performance improvements" | "Report generation is about 3x faster on datasets over 10k rows" |
| "Updated the API" | "API v2 endpoints added; v1 remains until 1 March 2027" |
| "New feature added" | "Added: schedule a report to email weekly, in Settings → Reports" |
| "Improved UX" | "The upload dialog no longer closes when you click outside it" |
Cadence
- Every release, not monthly. Aggregating into a monthly digest hides the signal you are trying to send, which is frequency of work.
- Small entries are fine. One line is a complete entry. A changelog with frequent small entries reads as healthier than one with rare large ones.
- Do not backfill. Entries dated after the fact are detectable and undermine the whole purpose.
- Do not stop. An abandoned changelog is worse than none, because the last date answers the question a buyer was asking and the answer is bad. If development pauses, say so once.
What a changelog does beyond informing users
- Each entry is an indexable page with a recent date. Freshness is a signal both search engines and AI assistants weigh, and a changelog produces it continuously without any writing effort beyond the entry itself.
- It is evidence in a sales conversation. A prospect asking "how actively is this developed" can be sent a URL instead of an assertion.
- It documents your own history. Six months later you will not remember when something changed or why. The changelog will.
- It sets expectations for breaking changes. Users who learn about a removal from the changelog are annoyed; users who learn about it from an error are gone.
Where it lives
- Reachable in one click from the site and from inside the product. A changelog behind a login cannot do any of the work described above.
- At a stable URL. `/changelog` and never anything else — it gets bookmarked and linked.
- Newest first. Every time. Nobody scrolls to find the latest entry.
- Optionally as a feed. RSS costs nothing to add and is how some users will actually read it.
Starting one today
- 1
Create the page with one entry
The most recent change you can date accurately. Do not backfill a year of history — a single honest entry beats a fabricated timeline.
- 2
Add it to the footer and the in-app menu
Discoverability is most of the value.
- 3
Write the next entry when you ship, not later
The habit only forms if it is part of shipping. Treat an unreleased change as unfinished.
- 4
Link it from your listings
Where a directory allows a docs or changelog URL, use it. Its presence is a quality signal to reviewers as well as to buyers.
A changelog is not documentation. It is a dated answer to the question every buyer of a small software product asks and almost never gets answered: is anyone still here?
More in Content & building in public
- How to Get Your First 10 Newsletter MentionsNewsletters are a reachable audience for a new AI product. How to get mentioned in ten of them: finding the right ones, becoming a source, and pitching.
- Case Studies for AI Products: A Template Founders Can CopyA case study structure that works for a solo founder with one or two users: the six sections, what evidence each needs, and how to get permission.
- Repurposing Your AI Product Launch Across 6 ChannelsOne launch, six surfaces: how to cut the same material for a blog, a thread, LinkedIn, a community, listings and a pitch without repeating yourself.