Product Changelog: How to Write One People Actually Read

A feature nobody knows about might as well not exist. You spent three weeks building it; announcing it takes twenty minutes; skipping the announcement forfeits most of the value. The changelog is the cheapest marketing surface you own — it converts work you already did into visible momentum.

And yet most SaaS changelogs are either dead ("Last updated: 14 months ago") or unreadable ("Fixed edge case in sync worker"). Both failures have the same two causes: writing for the wrong reader, and a publishing workflow with too much friction. Both are fixable.

What belongs in a changelog

The test for every entry: would a user do something differently after reading this?

That admits more than you'd think — new features, changed behavior, fixed bugs users actually hit, performance work they'll feel, pricing and plan changes. It excludes refactors, dependency bumps, and internal tooling. Those belong in your git history, which is a different document with a different reader.

Don't pad. An entry that exists to prove you were busy teaches users the changelog isn't worth reading. Three meaningful entries a month beat twelve trivial ones.

Write the outcome, not the diff

The classic failure is transcribing engineering into the changelog:

Refactored export pipeline to stream batches instead of buffering.

The user-facing version of the same work:

Large exports no longer time out. Exports over 10k rows now stream progressively — a 50k-row export that previously failed completes in about 20 seconds.

The formula: bold outcome first, one sentence of concrete detail after. Name what the user can now do, feel, or stop working around. Numbers beat adjectives ("about 20 seconds," not "much faster"). If you must mention the mechanism, put it in the second sentence where the curious can find it and everyone else can skip it.

Group entries by type — Added, Improved, Fixed — and date them. Give each entry a permalink, because a changelog entry is also an answer: to a support question, a sales objection, a "is this tool maintained?" check from a prospect. Entry pages get linked far more than changelog homepages.

The workflow problem is the real problem

Nobody plans to abandon their changelog. It dies operationally: publishing means opening the CMS, remembering what shipped since last time, reconstructing it from git, formatting, posting. That's an hour of friction per update, so it slips a release, then two, then the gap itself becomes embarrassing and the page quietly dies.

The fix is making the draft automatic so only the judgment is manual. SeggWat's changelog is built around a draft gate with automated sources feeding it:

• GitHub releases sync as drafts. Publish a release and it lands in your changelog queue via webhook — nothing goes public without you rewriting it for users first. The draft gate is what makes automation safe: automation captures that something shipped, you still write what it means.
• Completed feature requests feed in too. When you mark a request Completed on your public roadmap, SeggWat asks for the version and links the request to its changelog entry. The person who asked for the feature can follow the thread from their request to the shipped announcement — the loop closes itself.
• Publish per entry or clear the batch. Review drafts when you have twenty minutes; publish one or all.

Your recurring job shrinks to: open drafts, rewrite each as an outcome, hit publish. That's a workflow that survives a busy month. See the publish flow in 4 screenshots — a completed feature request arriving as a draft and going live in one click.

Distribution: don't make users come looking

A changelog page waits passively. Give it push channels:

• In-app badge. SeggWat's feedback widget shows a "News" badge when there are fresh entries — discovery happens inside the product, where the feature is one click from being tried.
• Email digest. Visitors can opt into a weekly summary. Weekly matters: per-release emails train people to unsubscribe.
• Atom feed. For feed readers and for piping entries into your own automations (a Slack channel, a social post draft).

One more free win: end entries that came from user requests with credit — "requested on our feedback board." It signals the board works, which recruits more feedback.

Start smaller than feels right

Backfill the last month, not the last year. Three good entries and a public page beat a perfect archive you never finish. Then let the drafts queue keep you honest.

Try SeggWat free — connect the GitHub app, publish your next release, and find the changelog draft already waiting.