okaihub

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

ElementRule
DateEvery entry, ISO or unambiguous ("12 Nov 2026", not "11/12"). The date is the signal
Version or release nameOptional, but consistent if used. Do not mix schemes
One line per changeWhat changed, for the user. Not what you refactored
GroupingAdded / Changed / Fixed, in that order. Only include a group if it has entries
Breaking changesFlagged at the top, with what to do about them
LinksTo 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:

UselessUseful
"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"
The right column tells a reader whether the change affects them. The left column tells them nothing at all.

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. 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. 2

    Add it to the footer and the in-app menu

    Discoverability is most of the value.

  3. 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. 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