Somebody evaluating your product reads the changelog for three things a marketing page cannot tell them: whether anyone is still working on this, what happens to their setup when something changes, and who the team writes for. Every entry is evidence for all three, whether or not it was written with an evaluator in mind. A changelog is the part of a website that is hard to stage, because it is a record with dates on it.
A person choosing between two products has a question that no feature list answers: is this thing alive. Pricing pages, feature pages and case studies are all written once and left standing, so they say nothing about last month. A changelog with dated entries is one of the few pages on a site that cannot look maintained without being maintained, which is exactly why people go there. It is also where a technical evaluator looks for how disruption is handled, because they are trying to price the cost of depending on you.
The evaluation reading is different from the customer reading. An existing customer opens a changelog to find out what changed in something they already use. An evaluator has no context to update, so they read the shape rather than the content: how often entries appear, how large they are, what kinds of change show up, and how the writing treats the reader. Most of what they take away is not in any individual entry.
| What they see | What they conclude | What to do about it |
|---|---|---|
| The newest entry is four months old | Either the product has stalled or the changelog has | Post small entries; a quiet month with one line beats a gap |
| Entries appear in bursts with long gaps | Releases are events, so support may be too | Say what the cadence is, or publish the small things between the big ones |
| No bug fixes anywhere | Either nothing breaks, which is not believable, or fixes are hidden | Publish fixes, including the ones nobody reported |
| Breaking changes appear with no migration note | Upgrades will cost them unplanned work | Every breaking entry names what breaks, when, and what to do |
| Entries are written in internal vocabulary | The team writes for itself; the docs probably do too | Name things by what the reader controls, not by the module that changed |
| Every entry is a feature announcement | This is a marketing feed, and the real record is elsewhere | Mix the kinds of change; a changelog that only celebrates is not a record |
The bug-fix line is the one people most often get wrong. Publishing fixes feels like advertising your defects
Cadence follows releases, not the calendar. The cost of stopping is not a missed post; it is a page whose most prominent fact becomes the date of the last entry.
Market4 turns one release note into a changelog page, a blog post, a mail-out and a week of social posts — and then tells you which of them brought anyone back.
A gap in a changelog is read as a gap in the product, and that reading is usually unfair. Teams stop publishing entries long before they stop shipping, because the work continues and the writing is what falls off the list. The cost lands on the reader who cannot tell the difference between a team that shipped nothing in March and a team that shipped plenty and wrote nothing down.
There are two honest ways to close a gap. Publish smaller entries, so that a normal month produces something rather than waiting for a release worth announcing. Or say plainly on the page how often entries appear, so a reader can calibrate: a changelog that says it is updated at each release, next to a product that releases quarterly, is doing its job even when the last entry is old.
A breaking change handled well in the changelog does more for an evaluation than a feature announcement does, because it demonstrates the behaviour they are trying to predict. Nobody chooses a product on the assumption that nothing will ever break; they choose on the assumption that when it does, they will be told in time and told what to do.
Technical evaluators do, and so does anyone whose job depends on the product staying maintained. They are not reading for the features, which the marketing pages already list. They are checking whether entries are recent, whether disruption is handled openly, and whether the writing treats them as the audience. A changelog is one of the few pages on a site whose freshness cannot be faked without doing the work.
Sometimes, and that is the honest answer. A changelog whose newest entry is a year old tells a reader something specific and unflattering, where an absent changelog tells them nothing. If you cannot keep it current, either commit to short entries at a cadence you can hold, or say on the page how often it is updated so the reader can interpret the gap correctly.
Yes. Fixes are evidence that somebody is looking, and a feed of features only is read as an edited record. Security notes need more care: say what was affected and what a user should do, without publishing a recipe for the problem. A short, factual security entry is a stronger trust signal than silence, which is often read as a fix that was made quietly.
Recent enough to be consistent with the release cadence you claim. A weekly product needs entries at least monthly before a gap starts reading as trouble. A product that ships quarterly can go longer if the page says so. What causes damage is not the interval itself but the mismatch between the interval and what the rest of the site implies about how fast you move.
A changelog entry that links well converts better than one that sells. The rule is destination, not persuasion: link where the reader goes to use the thing, and cut every link that exists to move them somewhere you wanted them.
A changelog migration is four decisions, not a copy and paste: where the entries live from now on, what address each one answers at, what happens to the links people already shared, and who writes the next entry.
