How to Write Release Notes People Actually Read

Release notes are the written account of what a release changed. They are among the few documents that every user of a product is eventually exposed to, and they are frequently the worst-written. The usual cause is that they are produced last, by the person who built the change, from their own point of view, in a hurry.

This guide sets out a method that produces notes people read. It applies equally to a public changelog, an internal engineering digest and a customer email.

Decide who the notes are for

There are usually three audiences. Users want to know what is different and whether they need to do anything. Support and success staff want to know what will generate questions. Engineers and auditors want to know exactly what shipped. These are different documents. If you try to serve all three in one block of text, you will serve none of them.

The practical answer is layering. Put a short, plain-language summary first. Follow it with grouped entries written for users. Keep technical detail, such as migration notes or deprecations, in a clearly labelled section at the end. Where the audiences differ greatly, write separate notes and link them.

Group the changes

Readers scan. Group entries under a small set of headings so that a reader can find what concerns them. A common and sufficient set is new features, improvements, fixes and, where relevant, changes that need action. Atlas drafts notes from the finished scope of a release in three groups: features, fixes and other changes. Use as many groups as your readers need and no more.

Order entries within a group by importance to the reader, not by the order in which they were merged. Put anything that requires action, or that removes behaviour, at the top of the notes, not at the bottom.

Word each entry for the reader

• Lead with the benefit or the behaviour, not the mechanism. "You can now filter tasks by label" tells the reader something. "Added label filter to the task query layer" does not.
• Use one or two sentences. If an entry needs a paragraph, it needs a link to documentation.
• Use the product's own words for features, the same words used on the screen and in the help pages.
• For fixes, describe the symptom the user saw, not the code that was wrong. "Fixed an error that stopped large files uploading" is readable. "Corrected an off-by-one in the chunker" is not.
• Say what changed, not that something was "improved". An unspecific improvement is noise.
• Name the date or version once, at the top. Do not repeat it in every line.

Be honest about what changed

Release notes lose their value the first time a reader finds a change that was not mentioned. Include removals, behavioural changes and known issues. A known issue stated plainly, with a workaround, costs less trust than a surprise discovered by a customer.

Do not describe a feature as available before it is. If a change is behind a flag or rolling out in stages, say so and state who can see it. Write only what the release contains.

A template

The following structure works for most products. Replace the bracketed parts.

• Title: product name, version or date, release date.
• Summary: two or three sentences stating the most important change and whether any action is needed.
• Action needed: changes that require users or administrators to do something, with steps.
• New features: one entry each, benefit first, with a link to documentation.
• Improvements: changes to existing behaviour.
• Fixes: the symptom that was corrected.
• Known issues: open problems with workarounds.
• Deprecations: what is going away and when.

Where release notes come from

The most reliable source of release notes is the release's own scope. If every change is a task with a clear title, the list of finished tasks is the skeleton of the notes. This is why task titles are worth writing well: they are read twice, once by the team and once by the customer.

In Atlas, choose Draft notes on a release and the platform writes Markdown from the finished tasks in its scope, grouped into features, fixes and other changes. The draft is a starting point. Edit the wording for the reader, save the notes and publish them inside the workspace. Saving new text withdraws an earlier publication, so what is published is what was reviewed. You can copy the result as Markdown to post in your own changelog or email.

Note the distinction between your workspace's release notes and the Atlas product changelog. The changelog is written by Atlas for all Atlas users. The notes in Release Management belong to the releases your own team ships.

Common mistakes

• Writing notes from the commit log. Commit messages are written for engineers and read poorly to everyone else.
• Leaving notes until after the release. Drafting them while checking readiness finds unclear scope early.
• Using internal names and ticket numbers as the only description.
• Hiding a breaking change in the middle of a long list.
• Over-promising. Describe what shipped, not what is planned.