What's new, better and fixed in this version of your product, written for the people who use it.
Most release notes are a commit log with the ticket numbers taken out. Users don't read those, and a month later they write to support asking for a feature you already shipped. Open the finished notes for Hedgerow, a made-up scheduling app, then use the prompt to turn your own changelog into something a customer reads to the end.
Who it's for
Product managers, founders and support leads. You publish the notes on release day, link them from the app's menu or a "What's new" badge, and paste the same link into the email that announces the release.
They're the wrong place for a breaking API change or a price increase. Those need a direct message to the people affected, with a date and what to do. A page also won't tell you who has opened it, so keep the in-app banner for anything users must act on.
What a good one contains
- A version and a date at the top. Support will ask a customer "are you on 3.8?", and the customer needs somewhere to check.
- Two sentences on what the release is about. Hedgerow's says this one is about the weather. A reader who stops there still has the main thing.
- New, improved and fixed, kept apart. People scan for the heading they care about. Whoever reported a bug goes straight to Fixed.
- Each change as something the user can now do. "Move a rained-off day in one go", where the ticket said "bulk reschedule". Name the button or screen so they can find it.
- Numbers where you have them. The week view opens in about one second and used to take four or five. "Faster" alone is what every release claims.
- Fixes described by their symptom. A user recognizes "payments recorded twice". They've never seen your ticket title.
- What they need to do, if anything. Here it's nothing on the web, and an app update on a phone.
- Earlier releases underneath. Three short entries, so someone who skipped a month can catch up.
Before you publish
Start from everything that shipped, then delete. Refactoring, dependency updates and anything still behind a feature flag don't belong, however much work they were.
Read each fix as the customer who reported it. Don't hide that it was broken, and don't make it sound like their mistake. Then ask support to check your wording against the tickets, because they know what users call things.
Keep one link for every release. Publish the new notes over the old page and move last month's into the list at the bottom, so the link inside your app always shows the latest version.
How to send it
As an open link. Release notes are for every user, and you'll link them from inside the app. Put them behind a password and nobody reads them.
Every page you publish gets one link that opens in any browser. You choose who can open it: anyone with the link, anyone with the password, or only the people and company domains you name, who sign in with Google or Microsoft. Change the page later and the link stays the same.
