Quick answer: A release note is the short text that announces what changed in a product release. The user reads it for the change and the value, not the engineering ticket number, and the best release notes are short, plain, and user-centered.

The structure

  1. The version and the date. The release and the timing.
  2. The headline. The change in one line.
  3. The value. What the change means for the user.
  4. The details. The how, where needed.
  5. The fix. The defects resolved.
  6. The next action. The thing the user can do now.

The headline

The headline states the change in the user's language:

  • The weak headline: "v2.4 released."
  • The strong headline: "You can now schedule posts across five platforms."

The feature announcement is the longer marketing version.

The value

For each change, the release note answers:

  • What changed.
  • What problem it solves.
  • What the user can now do.

The format is the change plus the benefit:

  • [Feature] — the change and the value.
  • [Improved] — the faster, simpler, or clearer behavior.
  • [Fixed] — the issue and the correction.

The grouping

The longer release is grouped:

  • New. The new capabilities.
  • Improved. The enhancements.
  • Fixed. The defects.
  • Deprecated or removed. The changes the users need to know about.

The grouping prevents the one-long-list problem.

The details

The details are included only when the user needs them:

  • The migration or the setting change.
  • The API and the data change.
  • The pricing change, linked to the pricing announcement.

The internals, the refactors, and the ticket numbers are left out.

The length

  • The small release: a few lines.
  • The major release: the grouped sections, under a page.
  • The user doesn't need the commit history; the changelog is separate.

The tone

The release note is written in plain language:

  • The simple verb: "You can now...," "The app no longer...,"
  • The human-signal review removes the generated tone.
  • The honest statement when the feature is limited.

The example

## v2.4 — October 11

### New
- **Schedule posts across five platforms.** You can now queue the
  launch set for the week in one place, instead of posting each one
  manually. The supported platforms are listed in the scheduling guide.

### Improved
- The editor now saves the draft within a second, so the interrupted
  session no longer loses the edits.

### Fixed
- The square image no longer crops the bottom of the caption in the
  Instagram preview.

The distribution

The release note is read in several places:

  • The changelog and the in-app modal.
  • The email and the launch email for the major releases.
  • The product update post and the social set; for the major release, the platform-sized images can be generated from the same release text, and a tool like Neatico produces the cards and the captions so the announcement looks consistent across the channels.
  • The store's "What's new" section; the app store description covers it.

The review

  • The claims are shipped and the screenshots match the release; the fact-check applies.
  • The breaking change is stated, not hidden.
  • The pricing change is announced separately and in advance.
  • The thanks to the customers who reported the issue are genuine.

What to avoid

  • The ticket number and the internal code name.
  • The "various bug fixes" with no detail.
  • The feature named in the engineering language.
  • The release note that reads like the marketing page.
  • The breaking change announced on the same day it ships.

Frequently asked questions

How detailed is the release note? The value sentence plus the detail the user needs; the changelog holds the technical list. Is the release note the same as the changelog? The changelog is the complete list; the release note is the user-facing selection. How often is it published? With each release; the monthly rollup works for the small continuous changes. Should the note include the screenshots? The major release benefits from the visual; the marketing screenshot guide covers it.

Write each change as the value to the user, keep the notes short, and state the breaking change early. The release note is read by the person who already uses the product.