Release notes customers actually read
A practical playbook for SaaS release notes: versioning, tags, length, and a What’s New widget that shows up where people already work.
Most release notes are written for the team that shipped, not the person who has to live with the change. They read like git logs. Customers skim once, miss the breaking change, and open a ticket two days later.
Good release notes are a product surface. They sit next to the app, they are versioned, and they answer three questions in under a minute: what moved, who it affects, and what to do next.
Write for the next session, not the commit
Open with the customer outcome. “Realtime sync across devices” beats “refactored the presence channel.” The git history is for you; the changelog is for the person who will hit the new behavior on Monday morning.
Keep a release to one story. If you shipped a feature, a fix, and a billing tweak in the same week, publish three notes — or one note with three clearly headed sections. A wall of bullets with no hierarchy is how breaking changes hide.
Version like you mean it
A visible version chip (v1.2.0) does more than look technical. It gives support a handle (“are you on 1.2?”), it gives enterprise buyers an audit trail, and it lets you mark #breaking without drama. Pair the version with a date and a one-line title. Reading time is a courtesy; if the note takes more than three minutes, you are writing a blog post.
Use a small, boring tag set. #feature, #fix, #perf, and #breaking cover almost everything a reader wants to filter. Inventing twelve categories is how filters die.
Put the notes where the product already is
Email digests still matter for people who asked to be notified. They do not replace an in-product What’s New badge. The badge catches the customer who never opened the last three emails. A Shadow DOM widget is the lowest-friction version of that: one script tag, your brand color, no CSS leaking into the host page.
Host a public timeline too. /changelog (or /c/your-slug) is the URL you paste into a sales call, a status thread, and a security questionnaire. Search and tag filters turn that URL into a self-serve audit.
A note template that holds up
Use the same shape every time so readers learn the rhythm:
- Title — outcome in the customer’s words.
- What shipped — three to seven lines, markdown, no internal jargon.
- Who is affected — plans, roles, or “everyone.”
- What to do — nothing / refresh / migrate by date.
- Tags — one or two hashes.
That is enough. Screenshots help when the UI moved. Deep links help when a setting changed. Do not paste the entire PR description.
Measure whether anyone read it
If you cannot see reactions, you are guessing. A 👍 or 🎉 on a release is a cheap signal that the note landed. Subscriber count tells you who wants the next one. Support volume on “did this ship?” is the lagging indicator — it should fall after the widget is on the app shell.
What a week of notes looks like
Monday: a #fix for the badge drifting under a sticky header. Four sentences, a version bump to v1.1.1, no email.
Wednesday: a #feature for yearly billing. Title in the customer’s words, a who-is-affected line for Starter vs Pro, a permalink CS can paste.
Friday: a #breaking default. Widget, public page, and a note to subscribers. The tag is the first thing on the card.
That cadence is more trustworthy than a quarterly “what’s new” PDF. Customers learn the rhythm. Support learns the URLs. You stop rewriting the same paragraph in five Slack threads.
Release notes are not a marketing campaign. They are how a SaaS product stays honest after the deploy. Write them like the customer is in the room, publish them where the customer already works, and keep the archive public so the history can speak when you are not on the call.