Release notes people actually read

Most release notes are written for the team that shipped the feature, not the customer who waited for it. That's why nobody reads them.

We've now watched hundreds of changelogs go out through Signal — some devoured, most skimmed, plenty ignored. The difference is rarely the product. It's the writing. The good ones follow a structure so consistent you can apply it as a checklist.

Lead with the outcome, not the change

"Refactored the checkout submission path" is a diff summary. "You'll never see a duplicate charge again" is a release note. The customer doesn't want to know what you did — they want to know what's different for them. Put the outcome in the first sentence, and the mechanism in the second, if at all.

Name the pain you removed

The best-performing updates we've measured share one trait: they acknowledge the annoyance they fix. "If you've ever exported members one page at a time — we're sorry, and it's over" outperforms a neutral feature description every time. Naming the pain proves you knew about it, which quietly says we're listening.

Keep the receipts small

• Three bullets beat ten. If a release genuinely has ten changes, it's two releases.
• One screenshot or none. A wall of images reads as marketing, not news.
• Link the docs; don't reproduce them. A release note is a headline service, not a manual.

Write in one voice, forever

Changelogs are read in aggregate. A customer scrolling your archive should feel one consistent narrator — same tense, same warmth, same confidence. This is exactly why we made Signal learn your tone from the updates you approve: consistency is a feature you compound over months.

A changelog is the only page on your marketing site your customers reread. Every retention conversation we've had this year

If you take one thing from this post: your next release note should answer "so what?" in its first ten words. The rest is polish.