Why release notes are marketing and documentation at once
A release note does two jobs. It is documentation: a factual record of what changed, when and for whom, which support agents, salespeople and customers' administrators will search for months afterwards. And it is marketing: the moment a customer decides whether a change is worth their attention, which decides whether the feature gets used. Teams that treat notes only as documentation publish accurate lists nobody reads. Teams that treat them only as marketing publish enthusiastic announcements that leave out the limits, the dates and the plans affected, and support pays for it.
The launch process already gives release notes a place. In the launch tiers table, a minor release gets a changelog entry, help documentation and an in-product note where useful, so for most releases the note is the whole launch. The product launches hub names the opposite failure: a significant capability that ships with a single line in the changelog because nobody tiered it. Larger launches use the note as one asset in the bill of materials, alongside the emails, pages and sales material the plan lists.
Notes are also read in a particular way. As the writing for the web guide summarises from Nielsen Norman Group's research on how users read on the web, most people scan a page rather than read it word by word, picking out headings, the first words of lines and anything that looks relevant. A changelog is scanned harder than almost any other page, because the reader is looking for the one change that affects them. The structure in this tutorial is built for that reader.
Before you start
Agree who owns the changelog. Product management or engineering supplies the facts; product marketing, or whoever owns the product's voice, writes or edits the notes; one named person decides what is published and keeps the structure consistent. Agree too how the facts reach the writer: a field on each release ticket, a short form, or a review where product walks through what is shipping. Notes written from memory after the release are where errors come from.
Gather the inputs each note needs: the current messaging hierarchy, so that notes use the same words as the website and the sales material; the plans, regions and roles the product is sold in, so that availability can be stated precisely; and the help centre, so that every note can link to the article that explains the change in depth. If the business has a house style, the editorial style guide tutorial is where naming and formatting rules for notes belong, rather than in a separate document.
Decide where notes will live before writing the first one: a public changelog page, a page inside the product, or both. A public page helps prospects and search engines see that the product is maintained; a page inside the product reaches people at the moment they are using it. Most products need the record in one place, with links to it from wherever customers look.
The steps
Decide who reads the notes and where they will see them
List the readers. Everyday users want to know what changed on the screens they use. Administrators want to know what they need to configure, announce to their teams or switch off. Buyers evaluating the product want evidence that it is improving in the direction they care about. Support, sales and customer success need the same facts before customers ask. Then list the places each group meets a note: the changelog page, an in-product panel or an in-app messageA message shown inside an app during a session the person started, such as a banner, modal or tooltip, needing no operating-system permission., an email digest, the help centre. Each entry is written once and shown in several places, so it must make sense on its own wherever it appears.
Set the scope: what gets a note and what stays internal
Write the rule down. Every change a customer could notice gets a note: new capabilities, improvements, fixes to problems customers reported, changes in behaviour, price or plan changes and removals. Purely internal work that changes nothing a customer sees stays in the engineering log. Removals and changed behaviour matter most, because a customer who finds a button missing without warning stops trusting every other note; retiring a feature needs a communication plan of its own, and the note is only its record. Several small improvements around one theme can share an entry, as the tiers guide suggests for bundling minor releases into a story.
Write the headline as the change for the user
The headline says what the reader can now do, or what now happens differently, in the reader's words, not the name of the ticket or the component. "Clinics can now send reminders by text message" beats "SMS gateway integration". This is the inverted pyramid applied to a single entry: the conclusion first, so that a reader who stops after the headline still has the point. Keep product and feature names consistent with the website and the messaging, and never introduce a new name in a release note that the rest of the company has not agreed.
Say why it matters and how to use it
Under the headline, a sentence or two explains what the change makes possible and for whom, followed by how to use it: where to find it, whether it needs switching on, and a link to the help article. The features, advantages and benefits chain keeps this honest: name the feature, say what it does that was not possible before, then the benefit to the reader. A benefit with no advantage behind it reads as an advert and is skipped. A screenshot or short clip helps when the change is visual; it does not replace the text, which has to work for people who cannot see the image.
State who has it and from when
Every entry says which plans, regions, platforms and roles have the change, and whether it is available to everyone now, rolling out gradually, or in early access. Customers who read about a feature they cannot find will contact support or assume the note is wrong. If availability will change, say so plainly and update the entry when it does. Date every entry with the date the change reached customers, not the date the work was finished. When a change reaches customers in stages, the guide to launching a feature that rolls out gradually plans the dated lines, messages and announcement around each stage.
Check every claim against its evidence
A release note that describes benefits is marketing communication, and the rules on claims apply to it as they do to an advert. The messaging hierarchy and proof points guide summarises the direction of the rules: the Advertising Standards Authority's codes require objective claims to be capable of substantiation before they are made, and the FTC's business guidance expects a reasonable basis for objective claims before publishing. "Faster", "more accurate" or "saves time" in a note need evidence on file, with the comparison stated. If the evidence does not exist, describe what changed and let readers judge the effect. This is educational guidance, not legal advice; claims that matter commercially go through whoever handles compliance.
Group entries and name things consistently
Give entries a small set of labels that readers can filter or scan by, such as new, improved, fixed and removed, and use the same labels every time. Group a release's entries by the area of the product they affect, in the order readers care about: changes that need action first, then new capabilities, then improvements and fixes. Use one name for each feature across notes, help articles and the product itself. Inconsistent naming is the most common reason a customer cannot find what a note describes.
Publish to the changelog and link from the product
Publish each entry to the changelog, newest first, with its date and labels, and link it both ways with the help article. Point to the changelog from inside the product, so that people can see what is new where they work, and from the help centre. The in-app message design guide covers putting a single announcement in front of the people who would use a feature, at the place it lives, with the record kept in an inbox for anyone who wants to read what changed. Brief support and customer-facing teams before the note goes live, so they are never learning about a change from a customer.
Send a digest only to people who asked for it
A periodic email that rounds up what is new is useful to many customers, but check its footing. The guide to promotional and transactional email, which lists the ICO's direct marketing guidance among its sources, gives the honest test: ask what would be left if the promotional content were removed. A digest written to encourage use of new features would leave nothing the recipient needs, so it is promotional and goes only to people who agreed to receive it. A notice that something customers rely on will change or stop working is a service message they need whatever their marketing preferences, and the transactional emailAn email triggered by a person's own action or account, such as a receipt, password reset or shipping notice, rather than a marketing send. definition explains why it must stay free of selling. Keep the two separate rather than hiding an announcement inside a service notice.
Correct mistakes in the open and keep the record
When a note turns out to be wrong, because availability changed, a feature was delayed or a claim overstated the effect, correct the entry, add a dated line saying what changed, and tell the people who acted on it if the error affected them. Never delete entries quietly: the changelog's value is that it is a complete record. Review the changelog when the help centre is reviewed, since the support channels and self-service guide ties help-centre maintenance to the release process, and outdated notes and outdated articles usually go together.
What a release note contains
Each entry answers the same questions in the same order, so that readers learn where to look.
| Part | What it says | Why it matters |
|---|---|---|
| Date | When the change reached customers | Lets support and customers match the note to what they saw |
| Label | New, improved, fixed or removed | Lets readers scan for the kind of change they care about |
| Headline | What the reader can now do, in their words | Carries the point for readers who stop after one line |
| Why it matters | What the change makes possible, and for whom | Turns a feature into a reason to use it |
| How to use it | Where it is, whether it needs switching on, link to help | Moves the reader from reading to trying |
| Availability | Plans, regions, platforms, roles and rollout state | Prevents support contacts from people who cannot find it |
| Action needed | Anything administrators must configure or tell their teams | Puts the changes that need work at the top |
| Evidence note (internal) | Where the proof for any claim is kept | Lets anyone check a claim before it is reused elsewhere |
The internal evidence note never appears on the public page; it sits on the ticket or in the changelog's source so that a salesperson or copywriter reusing a claim from a note can see what supports it.
Measure release notes by what they change rather than by views. The measuring launch success guide sets out the stages from discovery and first use to activation; for a change announced only through notes, the useful KPIA metric tied directly to an objective. is the share of eligible customers who try the change, and its activation rateThe share of new users or sign-ups who complete the activation event, the action marking first real value, within a set window., read alongside support contacts on the same topic.
A clinic booking software's changelog (illustrative)
Kestavine Bookings rebuilds its release notes
Kestavine Bookings, an invented appointment-booking software for physiotherapy clinics, had published release notes as a monthly list of developer change summaries, an average of 23 lines per month with titles such as "reminder service refactor". Support logged 140 contacts in a quarter from clinics asking how to do things a note had already announced. The product marketer rewrote the process: a field on each release ticket for the user-facing change, plans affected and the help article, and a changelog page with four labels and dated entries. The first rewritten entry led with "Clinics can now send appointment reminders by text message", stated that it was available on the two higher plans in the UK only, and linked the set-up article. A claim in the draft that text reminders "halve no-shows" was cut because the company held no evidence for it. The monthly digest, previously sent to every account email, was moved to the 2,100 contacts who had opted in to product news, while a separate service notice went to every administrator about a reminder setting that would change behaviour. In the following quarter, contacts asking how to use newly announced features fell to 55, and 38% of eligible clinics had sent at least one text reminder within six weeks of the note.
When a release needs more than a note, the tier decides what else it gets, and the launch planning and tiers guide sets out the plan, owners and bill of materials for feature and major launches.
Common mistakes
- Publishing ticket titles. Internal names and component labels mean nothing to customers; write the change in the reader's words.
- Leaving out who has it. A note that does not state plans, regions and rollout state sends readers to support.
- Burying removals and changed behaviour. Changes that need action go first, and a removal never appears only as a line among improvements.
- Unsupported benefit claims. "Faster" and "saves time" need evidence on file, or the note should describe the change and let readers judge.
- Inconsistent names. A feature called one thing in the note, another in the product and a third in the help centre cannot be found.
- Selling inside a service notice. A notice customers need stays free of promotion; a promotional digest goes only to people who asked for it.
- Deleting wrong entries. Correct them with a dated line; the changelog is valuable because it is complete.
- Treating the note as the launch for everything. A significant capability needs the tier its impact deserves, not one line in the changelog.
