Lorixen.
EN

A changelog page customers actually read

Short answer: A changelog customers read is written for them, not for your developers: one entry per release or week, a plain headline, a short "what this means for you", and a label such as New, Improved or Fixed. Put it at a stable URL like /changelog, link each entry to the relevant help article, and let people subscribe by email or RSS. Keep the roadmap and the technical release notes on separate pages so the changelog stays short and trustworthy.

Many small software products have a changelog that is either empty or a copy of commit messages. Neither helps. A good updates page answers the customer's real question, "what's different, and does it affect me?", in under a minute. It also quietly does sales and support work: prospects see an active product, and existing users discover features they'd otherwise ask support about.

Changelog, release notes or roadmap?

These three pages get mixed up, which is why many updates pages are confusing.

Page Audience Question it answers Typical content
Changelog / product updates Customers, prospects What changed recently? Short entries, newest first
Release notes Admins, developers, integrators What exactly changed in version X? Versions, technical detail, breaking changes
Roadmap Customers, prospects What's coming? Themes or planned items, no firm dates unless you can keep them

A small team can merge changelog and release notes into one page if the product has few technical users. Keep the roadmap separate: mixing "shipped" and "planned" on one page makes people unsure what actually exists.

The page blueprint

1. A stable URL and an index

Use one permanent address, such as /changelog or /updates, linked from your site footer, help center and in-app menu. Show newest entries first, with a date on each. Paginate or archive by month once the page gets long.

2. Filters by label

Let readers filter by category. Keep a Changelog, a widely used convention for project changelogs, groups changes under Added, Changed, Deprecated, Removed, Fixed and Security. For a customer-facing page, simpler labels often read better:

  • New for new features
  • Improved for changes to existing features
  • Fixed for bug fixes
  • Heads-up for anything removed, deprecated or changing soon

Keep the mapping consistent so "Heads-up" always means the customer may need to act.

3. The entry itself

Each entry needs:

  • Date, written in full (not "last Tuesday")
  • Label or labels
  • Headline in the customer's language: "Export invoices to CSV", not "Refactor export service"
  • Two or three sentences on what changed and why it helps
  • Image or short clip for visual changes
  • Link to the help article or setting
  • Who it applies to if not everyone: which plan, platform or role

Keep a Changelog makes the same point from the other direction: it warns against using commit log diffs as changelogs because they're full of noise, and says a changelog entry should document the noteworthy difference, often across several commits, for end users.

4. An "Unreleased" or "Coming soon" strip, carefully

Keep a Changelog suggests an Unreleased section at the top to track upcoming changes. On a customer page, use it only for things that are finished and waiting to ship, and only if you're confident. If dates slip often, leave it out.

5. Version numbers, if you have them

If customers install or integrate your software, include version numbers. Semantic Versioning describes the MAJOR.MINOR.PATCH convention: a major version for incompatible API changes, minor for backward-compatible new functionality, and patch for backward-compatible bug fixes. Using it consistently tells technical customers at a glance whether an update needs their attention. For a web app that everyone gets automatically, dates are usually enough.

Entry templates (hypothetical examples)

The examples below are invented to show the format.

New — 14 October Send invoices straight from a job You can now create and send an invoice from inside a finished job, without retyping the customer's details. Open any completed job and choose "Create invoice". [How invoicing from jobs works]

Improved — 21 October Faster search on large accounts Search results now load noticeably faster on accounts with many records. No action needed.

Fixed — 21 October Calendar showing the wrong week after time change Some users saw the calendar open on the previous week after the clocks changed. This is fixed.

Heads-up — 28 October Old export format retiring The legacy XLS export will be removed at the end of next quarter. Switch to CSV or the new Excel export in Settings → Exports. [Export options]

Notice what they share: a concrete headline, one practical sentence, and a next step.

Getting it read

  • In-app announcement. A small "What's new" badge or panel that links to the latest entries. Show it once per entry, not on every login.
  • Email digest. A monthly round-up to customers who opt in, with the three most useful changes, not every fix.
  • RSS or Atom feed. Cheap to add, and some technical customers and integrators prefer it.
  • Help-center links. Every feature article should link back to the changelog entry that introduced it, and vice versa.
  • Support macros. When a fix ships, reply to the customers who reported it, linking the entry.

SEO for update pages

Changelog pages rarely rank for much on their own, and that's fine. A few basics help:

  • Give important entries their own URL with a descriptive title, so "export invoices to CSV [product name]" can find it.
  • Use real dates in the page, not only relative times.
  • Link from entries to the feature or help page that should rank, rather than competing with it.
  • Avoid publishing dozens of near-empty entries ("minor fixes"); group small fixes into one weekly entry.

FAQ

How often should we publish?

Whenever there's something customers would notice, grouped weekly or fortnightly if you ship small changes daily.

Should every bug fix be listed?

List fixes customers reported or would notice. Internal fixes can go into a single "other fixes" line.

Do we need a changelog tool?

Not to start. A simple page in your CMS or docs site works; dedicated tools add widgets, subscriptions and feedback.

What about breaking changes?

Label them clearly, give a date, explain what to do, and email affected customers directly as well.

Building a product and want a release routine that customers notice? Tell us what you ship and how often.

Sources

WhatsAppLet’s talk