How to write release notes people actually read

How to write release notes people actually read: one entry per user-visible change, the user's new ability first, a fixed version-and-date line, and one link to the page that explains it. Keep the note short enough to scan in a lift. A release note is an announcement, not a second changelog.

Most release notes fail for a boring reason. They describe what the team did, in the order the team did it, using the team's internal names. The reader wants to know one thing: can I do something now that I could not do yesterday? Write for that reader and the format almost writes itself.

Why release notes drift into changelogs

A changelog is a running record. A release note is the short announcement attached to one version. The two get mixed because both are written after the same code ships, by the same person, from the same ticket list. Once the ticket list becomes the outline, the note turns into a diary of implementation.

Keep a Changelog puts the distinction in one line: changelogs are for humans, not machines, and a dump of commit messages is not a changelog (keepachangelog.com, accessed 2026-10-18). The same test applies to release notes. If an entry only makes sense to someone who already knows the internal name of the service, it is not ready for the reader.

If a change has no visible effect, it usually belongs in the changelog, not in the release note.

How to write release notes: the four parts of an entry

Every user-visible entry answers four questions in this order: what changed, who it affects, what the reader should do, and where to read more. The first two are one sentence each. The third is often "nothing", and that is fine. The fourth is one link, not a paragraph of explanation.

The order matters because it matches how people scan. They read the first few words of each line, stop when a line looks relevant, then decide whether to click. A note that opens with "We refactored the billing service" gives them nothing to stop on.

The template you can copy

This is the whole deliverable. Put the fixed header at the top, then one block per change. Delete the labels in the final version if your audience already knows the pattern, but keep the order.

## 2026-10-18 · v1.4.0

**New**
- Export a product profile as CSV. Available on every plan. Nothing to enable.
  Details: /help/export-product-profile

**Improved**
- Directory submissions now keep the last checked date. No action needed.

**Fixed**
- The launch checklist no longer resets after a page refresh.

**Action needed**
- If you connected a custom domain before 1 October, re-check the DNS record.
  Details: /help/custom-domain

Two rules make the template survive contact with a real release. First, the version and date go in the header, not in every line. Second, each entry starts with the user's ability, not the component name. "Export a product profile as CSV" passes. "CSV exporter v2" does not.

What to include, and what to leave out

Use the change type, not the size of the diff, to decide. A one-line fix that changes what the reader sees belongs in the note. A week of internal work that changes nothing visible does not.

Pricing deserves its own note because it changes a decision, not a screen. A pricing change buried in a bullet list will be missed, and the support message that follows will cost more than the extra note.

Security fixes need a judgement call. Tell readers what to do and which versions are affected. Do not publish a reproduction recipe before the fix has reached everyone. If you cannot say the second part safely, say less and link to the advisory.

How to reuse one note across channels

Write the note once, then change the container, not the facts. The changelog page keeps every entry. The in-app message keeps the entries that affect the current screen. The email keeps the one entry that changes a decision. A directory or community post keeps the entry that a new reader can understand without context.

The reuse step is where most teams accidentally create two versions of the truth. Keep the date and the version string identical everywhere. If the changelog says v1.4.0 shipped on 18 October, the email cannot say "this week" without a date somewhere in the message.

Where release notes go wrong

The failures are predictable, and each one has a visible symptom.

1. The note is a commit log. Symptom: entries name services, branches or ticket numbers. Fix: rewrite from the reader's screen backwards.
2. Every release is "exciting". Symptom: the same three adjectives appear every month. Fix: delete the adjective and keep the verb. A note can be plain and still be useful.
3. The note arrives after the support inbox does. Symptom: users ask why something changed before the note is published. Fix: publish the note with the release, not after the complaints.

There is a fourth failure that is harder to see: writing a note for a change nobody can find. If the new ability lives behind three menus and the note does not say where, the note is technically accurate and practically useless. Add the path, or add a screenshot, or link to the page that shows the path.

What we have not measured

We have not measured whether a better release note changes retention, upgrades or support volume. No public study we could verify isolates that effect, and we are not going to invent one. What we can say is narrower: a note written in the reader's order is easier to scan, and an entry with an action line produces fewer "what do I do now" replies. That is a writing judgement, not a measured outcome.

Common questions

How long should a release note be?

As long as the user-visible changes require, and no longer. One change can be three lines. Ten changes can still be under a screen if each entry is one sentence. If the note needs a table of contents, it is probably a changelog page, not an announcement.

Should I write release notes for every deploy?

No. Write them for every release a reader can notice. A deploy that changes nothing visible does not need a note. A deploy that changes a button label does, because someone will notice and wonder whether they misremembered.

Do release notes help search or AI answers?

They can, but not because of the word "release". A dated page that names the feature, the plan and the action is a useful landing page for people searching the feature name later. A page of version numbers with no feature names gives a search engine very little to match. We have not measured citation lift from release notes, so treat this as a structural argument, not a promise.

Where should the note live?

One canonical URL per version, with the date in the page and in the URL if your system allows it. Cross-post the short version to the channels that need it, but keep the canonical page as the place the link points to. If you publish the same text in five places with five different dates, you have made five sources of truth.

Next step

Take the last release you shipped and rewrite one entry with the four-part order. If the entry gets shorter and more specific, the template is working. If it gets longer, you are probably trying to explain the implementation instead of the ability.

Release notes are one input to the wider content workflow. The same reader-first rewrite applies to the content brief you hand to a writer, and the same channel logic applies when you adapt a product description for every channel. When the note is ready, publish it where the product lives and keep the content workflow in one place so the next release does not start from a blank page.