The short version
- Four groups read release notes, and they want different things from the same document.
- Whether somebody reads the second one is decided by whether the first was worth the time.
- They're not a marketing announcement, and writing them as one loses the audience that uses the product.
- A version number isn't a title.
Release notes are the announcement that something shipped, written for the people affected by it. That's the definition, and the useful part of it's the second half, because who they're written for decides everything else about them.
What are release notes?
A short published statement, attached to a version or a date, saying what changed in the product and what the reader should do about it.
Three properties follow from that and they're worth separating, because most confusion about release notes is one of them being assumed.
They're an announcement. They go out. A reader receives them rather than going to look, which is why the first sentence carries almost all the weight.
They're attached to a moment. A release note describes one release. It's not a running history, which is what a changelog is.
They're for the affected, not the interested. The audience is people using the thing, not people evaluating it.
There's a changelog with real releases on it if you want to see the shape, and the demo is open without an account.
Want these published and delivered rather than written and forgotten? Ten changelog tools, checked on their own sites for email, a feed and a widget.
Who reads them, and why
Four groups, and they want different things from the same document.
| Who | What they want | What they do with it |
|---|---|---|
| Somebody who asked for one of the items | Confirmation their thing shipped | Go and use it, or stop waiting |
| Somebody who has to act | The breaking change, up front | Schedule work |
| A support person | What changed, so they can answer tickets | Read all of it, once |
| An evaluator deciding whether to buy | Evidence the product is alive | Read three entries and the dates |
The first group is the one release notes are for and the one most often forgotten. Somebody who asked for a feature six months ago and never learns it shipped has been let down twice, and they're the reader most likely to have been told by nobody.
The fourth group is why a changelog is a marketing asset by accident. An evaluator doesn't read the content. They read the cadence and the dates.
Release note or changelog entry?
They overlap enough that the words get used interchangeably, and the distinction is worth keeping.
| Release note | Changelog entry | |
|---|---|---|
| Shape | An announcement | A record |
| Audience | People affected now | Anybody, later |
| Tense | This is what we just shipped | This is what happened on this date |
| Length | A sentence and a grouped list | Often one line |
| Where it lives | Sent, and on a page | On a page, in order |
In practice one artefact does both. You write a release note and it becomes an entry in the changelog.
That's fine, and the thing to get right is that the release note reads as an announcement on the day and still reads as a record two years later, which means no "as you know" and no references to last week.
What makes somebody read the second one
Whether the first one was worth the time.
This is the whole game and it's decided by two things. Did the note contain something the reader cared about, and could they tell within one sentence. A release note that buries the one relevant item under nine irrelevant ones has spent the reader's attention and returned nothing, and the next one gets skimmed.
The mechanical consequence is to put the most consequential item in the first sentence, every time, even when it's a fix, not a feature.
What they are not
Not a marketing announcement. A launch post is written for people who don't use the product. A release note is written for people who do, and mixing them produces something that serves neither.
Not documentation. The note says the filtering exists. The documentation says how it works. A note that tries to teach becomes too long to skim.
Not a commit log. A list of merged branches is a record of work, not of change. The reader can't tell which of it affects them.
The mistakes
Version numbers as titles. 2.4.1 isn't a title. Nobody can tell it from 2.4.0.
Publishing to a page nobody visits. If it's not sent or shown where people already are, only the support team will read it.
Skipping the boring releases. A month of silence reads as a stalled product, even when it's not. A short note saying three bugs were fixed is better than nothing.
Writing them a week later. Everything gets compressed into "various improvements", because nobody remembers.
How do you do this without a tool?
A page with an entry per release, newest first, each with a date, a title with words in it, and a grouped list. Send a link when a release matters.
The discipline problem is writing it at all when the release is small, and the shortcut people take is batching a month of releases into one note, which is how "various improvements" gets written.
How does this product do it?
A release has a name, a published date, a markdown body, a featured flag that pins it to the top of the page, and the list of items that went into it.
The list comes off the board rather than being typed. It's the cards that reached the completed column, each with its heading, the category it was filed under, and the number of people who voted for it.
That last number is the part worth noticing for the first audience above. A release note generated this way can say that the thing shipped and how many people asked for it, and the people who asked are known, not guessed at.
The announcement banner strips the formatting out of the body and cuts it at 120 characters, which is why the first sentence gets the weight.
The changelog page covers the rest.
What a changelog is covers the record half of the pair, and what belongs in a release note covers each section.
14 days, a card at signup, then $9 or $39 a month.