How to write release notes people actually read
Most release notes fail the same way: they describe what the team did, in the team's words, published somewhere the team looks. The user's question is different — "what can I do now that I couldn't do yesterday, and does it affect me?" — and a note that doesn't answer it in the first line gets skimmed past.
The fix isn't better prose. It's a handful of mechanical habits.
1. Decide who it's for before you write a word
A developer reading API release notes wants exact behavior changes and migration steps. An end user wants to know whether the thing they complained about is fixed. Aha's guide to release notes makes the point plainly: the audience determines the content, the tone, and even who should write it.
If you serve both audiences, write two artifacts, not one compromise document. See changelog vs. release notes for how to split them.
2. Lead with what the user can do now
Not "Refactored export pipeline for improved throughput." Instead: "You can now export reports over 10,000 rows without the job timing out."
The test: could a customer who never reads your code understand the sentence, and would they know whether it applies to them? ProductPlan's advice is the same — plain language, no internal feature names, no implementation detail.
3. Group into new, improved, fixed
Three headings cover almost everything a SaaS product ships. Readers scan for the section they care about; support agents jump straight to "Fixed." A loose, consistent structure beats clever formatting — if you want one to copy, we keep a release notes template you can paste in.
Keep entries short. One bold line stating the change, one or two sentences on why it matters. If an entry needs four paragraphs, it deserves a blog post, linked from the entry.
4. Acknowledge bugs honestly
"Minor fixes and improvements" is the sentence that teaches users to stop reading. If you fixed a bug that signed people out early, say exactly that. The users who hit the bug are the most motivated readers you have, and a specific fix line is the cheapest trust you'll ever build.
5. Show the change
A screenshot or a short GIF communicates a UI change faster than any paragraph. Companies whose release notes get shared — Linear, Figma — put a visual on nearly every entry, a pattern that shows up in every roundup of strong examples. We pulled apart what the good ones do in release notes examples worth stealing from.
6. Deliver them; don't just publish them
Customers will not visit your release notes page on their own. Beamer's guide is blunt about this: you need a delivery channel — an in-app widget, an email digest, a Slack or Discord post — because nobody searches for release notes.
Match the channel to the audience. Developer-facing changes go where developers already are; end-user changes go in-app.
7. Tell the people who asked, directly
The highest-read release note is the one that lands in front of the person who requested the feature. A generic broadcast has to fight for attention; "the thing you asked for in March is live" does not.
Doing this by hand means someone remembering, at ship time, who asked months ago — which is why it rarely happens. We build Modem partly because of this step: it tracks who requested what from Slack, support, and email, and when the PR that resolves a request merges, it matches the work back to the requesters and drafts the release note and follow-ups with those people already attached. The matching survives channel-hopping because Modem keeps requesters and topics linked in one context graph — the person who asked in email and again in Slack is one entry, not two. If your requests already live on a public voting board, the board's built-in status notifications cover a version of this and Modem is not required for it.
Whatever tooling you use, the principle stands: the release note is the broadcast; the requester follow-up is the part that changes how customers feel about you. More on that in how to notify the customer who asked.
The smallest version you can start this week
Take your next release. Write three headings — new, improved, fixed. Under each, one bold sentence per change, phrased as what the user can do now. Add one screenshot. Post it in the one channel your users actually read. Then pick the single feature with the clearest requester and message that person directly.
That's the whole practice. Everything else is scaling it.
