Writing Release Notes People Read

Most release notes are a changelog with a nicer font: a list of things that changed, ordered by whatever order the tickets closed in, written for the team that made the changes rather than the people affected by them. They get skipped, which is a shame, because release notes are one of the few pieces of writing that reach every user of a product at the moment they are most receptive to learning something about it.

What release notes are for

Three audiences, with genuinely different needs, and the mistake is writing one document for all three without noticing.

Users want to know what is different for them, whether they need to do anything, and whether the thing that annoyed them is fixed. They do not care about the internal refactor.

Administrators and integrators want to know what breaks: API changes, configuration changes, migration steps, deprecations, minimum versions. They need warning, and they need it before the release, not with it.

Internal teams — support, sales, customer success — want to know what will generate questions and what they can now tell customers.

A single set of notes can serve all three if it is structured so each can find their part quickly. It cannot serve all three if it is a flat list.

Structure

Lead with what changed for the reader, not with the version number. "Version 4.2.0" as the opening line tells nobody anything. A one-paragraph summary of the release — what it is mainly about — orients everyone in five seconds.

Then, in this order:

1. Breaking changes and required actions. First, always, even in a release where they are minor. A reader who stops here must not have missed something that will break their system. If there are none, say "No breaking changes" explicitly — its absence is information too.
2. New features, with enough detail to know whether to care and a link to the documentation.
3. Improvements to existing behaviour.
4. Fixes, described by the symptom the user experienced rather than the internal cause.
5. Deprecations, with the removal timeline.
6. Known issues, if any.

Within each section, order by impact, not by ticket number. The change affecting everyone goes above the change affecting the four customers using an obscure integration.

Writing the entries

Describe the symptom, not the cause. "Fixed a null-pointer exception in the export handler" tells a user nothing. "Exporting a report with no rows no longer fails silently" tells them whether their problem is fixed. The internal cause belongs in the commit, not the notes.

Use the user's vocabulary. Internal names for features leak into release notes constantly, and readers cannot map them to what they see on screen. If the button says "Share", the notes say "Share", not "the ACL propagation dialog".

Say what to do, not only what happened. A breaking change entry should include the migration step. "The format parameter is now required" is half an entry; "The format parameter is now required — add format=json to existing calls to preserve current behaviour" is a complete one.

Be honest about regressions. A release that broke something and fixed it in a patch should say so. Users find out anyway, and the notes that acknowledge it are the ones that get believed.

Skip the invisible. Internal refactors, dependency bumps, test improvements — these belong in a changelog, not in release notes. Including them pads the document and trains readers to skim.

Keep entries to one or two sentences. Anything longer belongs in documentation, linked.

The general craft applies: plain language business documents and concise writing: cut your word count.

Timing

Breaking changes need advance notice, proportional to the work they impose. A deprecation announced in the release that removes it is not a deprecation. The convention that works: announce the deprecation, keep the old behaviour working for at least one or two release cycles, warn in the interim, then remove — and say in each set of notes that the removal is coming.

Publish notes at release, not after. Notes that arrive two days later are read by nobody, because the questions were asked and answered in the meantime.

Pre-announce large releases to administrators separately. The people who have to plan an upgrade window need more than the same document everyone else gets.

Versioning that helps readers

Version numbers communicate, if you let them. Semantic versioning — major for breaking changes, minor for additions, patch for fixes — lets a reader assess a release before reading a word. Its value is entirely in being followed strictly: one breaking change shipped in a minor version teaches users that the scheme means nothing, and they will read every set of notes in full thereafter, or more likely none.

Whatever scheme you use, state it somewhere and hold to it.

Distribution

Release notes tend to be published in more places than they are maintained, and the copies drift.

• One canonical location, versioned and permanently linked. Everything else points at it.
• In-product notification for user-facing changes, with a link rather than the full text.
• Email or a feed for administrators, who need to be told rather than to check.
• An archive of past releases, kept indefinitely. "What changed between the version we are on and the current one" is a question every long-lived deployment asks, and answering it requires history.
• A PDF rendition per release if you operate in a regulated environment where the release record must be fixed and retained — the same versioning discipline as employee handbooks and policy documents.

The internal version

Release notes are frequently the only durable record of what shipped and when, which makes them worth writing even for internal tools that have twelve users.

For internal audiences, add two things you would leave out publicly:

• Why, briefly. Internal readers benefit from knowing the reasoning, and it saves the same question being asked in three channels.
• Who to ask. A name or a channel per significant change.

This overlaps with the record-keeping documents: writing a decision log and giving a clear project status update.

A checklist before publishing

• Does the first paragraph say what this release is mainly about?
• Are breaking changes at the top, with migration steps?
• Is every entry written in terms of what the user experiences?
• Would a reader who skims only the headings know whether they need to act?
• Are internal names, ticket numbers and jargon removed?
• Are links to documentation present and correct?
• Is the removal timeline stated for every deprecation?
• Does anything here need to reach administrators earlier than everyone else?

More generally: proofreading checklist before you hit send.

Summary

Write release notes for the people affected rather than the people who did the work: lead with a sentence saying what the release is about, put breaking changes and required actions first with their migration steps, describe fixes by symptom rather than cause, and leave internal refactors out entirely. Announce deprecations at least a cycle before removal, publish at release rather than after, and keep an archive — the question "what changed between our version and current" is asked constantly and can only be answered from history.