Kasra Vaziri
All essays
Building in Public

The Underrated Power of a Public Product Changelog

A public product changelog is one of the highest-ROI habits a team can build — it shows momentum, builds trust, doubles as marketing, and forces shipping discipline. Here's what good ones look like and how to run one.

Kasra Vaziri7 min read

Most teams treat their changelog like a compliance task — a dusty page someone updates when they remember, buried two clicks deep, written in the language of Jira tickets. That's a waste. A public product changelog is quietly one of the highest-ROI habits a team can build, and almost nobody runs it like it matters.

I've come around to a strong opinion on this: if you ship software and you don't keep a real, public changelog, you're leaving trust, marketing, and shipping discipline on the table — three things you'd normally pay dearly for. The page costs you almost nothing. The habit changes how your team works.

Why a public product changelog is worth the trouble

A changelog does four jobs at once, which is rare for anything that fits on one URL.

First, it shows momentum. A page with a dated entry every week is the most honest signal a company can send that it's alive and improving. Compare that to a competitor whose "What's New" stops in 2023 — you can feel the difference in your gut before you read a word.

Second, it builds trust. When you tell people exactly what changed and why, you're treating them like adults. This is the same logic behind the whole build-in-public movement: transparency compounds. Data from a study of 68 bootstrapped apps found that build-in-public was the single most-used distribution channel in the sample — 43 of the 68 used it, and the researchers landed on a line worth taping to your monitor: it's "a trust amplifier, not a traffic channel." A changelog is build-in-public for people who don't want to run a Twitter account. You ship in the open without performing for an audience.

Third, it's marketing that doesn't feel like marketing. Every entry is a small, concrete proof point: we noticed this, we fixed it, here's the screenshot. Tools built around this — like Beamer, whose in-app "boosted" announcements claim 3x more engagement than passive ones — exist precisely because surfacing what's new drives real adoption. You built the feature already. The changelog is how anyone finds out.

Fourth, and most underrated: it forces shipping discipline. When you know an entry is going up every Friday, you ship something worth writing about every week. The empty changelog is a confession. The deadline does quiet, useful work on your roadmap.

What a good one actually looks like

The best public changelogs aren't logs at all — they read like a tiny product blog. Look at the people doing it well.

Linear's changelog ships on a roughly weekly cadence, and every meaningful entry comes with a real screenshot or short video plus a paragraph on why the feature exists, not just that it landed. It reads like the product team is proud of the work, because they are.

Stripe's changelog is the opposite aesthetic and just as good: tightly versioned and dated, one change per entry, with the deep technical detail walled off so a non-engineer isn't drowned in it. Precision is its own kind of trust.

GitHub's changelog goes wide — multiple entries most days across dozens of product areas — and earns it with category filters and an RSS feed, so a power user can subscribe to only the corner they care about. Volume without filtering is noise; volume with filtering is a service.

And Basecamp's updates from 37signals prove you don't need any of that polish. Short, dated, opinionated entries in plain confident English. No images, no taxonomy — just a clear voice making a clear point. The lesson across all four: pick a format, then be relentlessly consistent so people can scan it without relearning it every time.

How to write a user-facing entry

This is where most changelogs die. They get written by whoever closed the ticket, in the words of the ticket, and the result reads like Fix async loop timing — true, and useless to the human who has to live with the product.

Write for impact, not implementation. Mintlify, after studying the best developer-tool changelogs, put the first principle plainly: "write for human impact and understanding" — say what the change does for the reader, then keep only what matters. So instead of "Fix async loop timing," you write "Dashboards no longer freeze when you generate a large report." Same fix. One of them a person can feel.

A few rules I hold to:

  • Lead with the benefit. The first six words should tell a busy reader whether they care.

  • Say why, not just what. "We added bulk archive" is a fact. "Teams kept asking for a way to clear out finished projects without deleting them, so we added bulk archive" is a relationship.

  • One change per entry. Bundling five things into one paragraph means nobody reads any of them.

  • Flag the breaking stuff loudly. Prefix it, put it first, don't make people find out the hard way.

  • Cut the internal vocabulary. Your service names and ticket numbers mean nothing to the reader. Translate.

The voice can be yours — Basecamp's is dry and certain, Linear's is warm and proud — but the discipline is the same: every entry should pass the test of a real user reading it and knowing, in one breath, what just got better for them.

Cadence is the whole game

A changelog's value is almost entirely a function of rhythm. One brilliant entry a quarter is worth less than a plain, reliable entry every week, because reliability is the signal. People learn that you ship, and they start checking.

Pick a cadence you can actually hold. Weekly is the sweet spot for most teams — frequent enough to feel alive, slow enough to have something real to say. If you ship constantly, like GitHub, go faster but add filters so the firehose stays usable. If you ship in bigger arcs, biweekly or monthly is fine; what kills you is irregularity, the page that goes quiet for three months and screams "this company is stuck."

Treat the cadence as a commitment, not an aspiration. Put it on someone's plate by name. Batch the small fixes into the regular entry rather than letting them vanish unmentioned — those small fixes are exactly the evidence that you're listening. And don't wait for the page to be perfect. A plain dated list, updated every week, beats a beautiful design that never gets touched.

There's a deeper payoff here that connects to a problem I've written about before. Most of what teams build goes unused not because it's bad but because nobody knows it exists. A changelog is the cheapest re-engagement channel you have — a standing invitation for users to come back and discover the thing you already built for them. The work is done. The changelog is how it gets used.

The takeaway

A public product changelog is a small habit that pays in four currencies at once: momentum, trust, marketing, and discipline. It's build-in-public without the performance, a marketing channel without an ad budget, and a deadline that quietly makes your team ship better. The bar to start is embarrassingly low — a dated page and the discipline to add one honest, user-facing entry every week.

Open the page. Write the first entry today, in plain language, about something you actually shipped. Then do it again next week. That's the whole secret. What did you ship this week that nobody knows about yet?

Sources

The newsletter

Think more clearly about product

One email when I've got something worth your attention — an essay, a hard-won lesson, or a new tool. No filler, no fixed schedule. Unsubscribe in a click.