Release notes examples, the same release written twice

The two release notes examples below are the same release written twice, and almost every bad release note is bad for the one reason the first of them shows.

It was written by the person who shipped the thing, in the vocabulary they used while shipping it, for a reader who wasn't in the room.

That's the hardest thing about writing them, not laziness. You have spent two weeks inside a problem and the words you've for it are the words of the inside. The customer has never seen the inside and never will.

So this post is twelve release notes written twice. On the left, the version a team actually writes. On the right, the same release for the person receiving it. Nothing here's copied from anybody's site. Each pair is built to show one specific move, and the moves are worth more than the examples.

Why do release notes get written for the wrong reader?

Three reasons, and only one of them is about writing.

The first is that the note is usually written last, by whoever merged the change, in the two minutes before the deploy. At that point the only description that exists is the one in the pull request, and that description was written for a reviewer.

The second is that the team knows the old behaviour and the customer doesn't. A team writes now supports nested tags because they remember that it used not to. A customer reads it and has no idea whether this is new, fixed, or something they should already have been able to do.

The third is that nobody has decided who the note is for. A release note aimed at everybody is aimed at nobody, and the first casualty is the person who asked for the thing, who is the only reader guaranteed to care.

There's a board doing this already if you want to look at one, and the demo is open without an account.

The twelve, each written twice

The middle column is what a team writes. The right column is the same release, and the move is named underneath the table.

The moves, in the order they appear.

One and two replace the mechanism with the moment. Nobody outside your company knows what an indexer is. Everybody knows what it feels like when search is slow.

Three and seven refuse the word improved. Improved is what you write when you haven't decided what actually changed. Both replacements name the specific thing, and seven does it without inventing a number, because a made up percentage is worse than no percentage.

Four and ten replace the container with the contents. A version number and a thank you're both about the release rather than about what's in it.

Five replaces the ticket with the symptom. The reader has never seen your tracker. They have seen the bug.

Six answers the question a setting always raises, which isn't what does it do but what does it stop happening to me.

Eight and nine put the breaking change first. Nine is the worst entry on the list before its rewrite, because burying a breaking change inside several updates is the one release note mistake that costs somebody a working day.

Eleven closes the loop it opens. Announcing a beta with no way in is an advertisement, not a release note.

Twelve is the one most teams skip, and it's the one that buys the most credit. A week with nothing user visible in it, said plainly, makes every other entry believable.

How much of a release note actually reaches anybody?

Less of it than you wrote, because the note most people see isn't the note you wrote.

On our side, publishing a release sends a message, and that message isn't built from the body you wrote. It's built from the headings of the cards in the release.

Your voters get their own items in bold and everything else in the release arrives as one small line underneath. The paragraph you spent time on stays on the page for whoever clicks through. The mechanism is written up here.

So the heading somebody typed on a card months ago, in a hurry, is the release note. Fix the headings before you publish and the entire message improves without your writing anything new.

The second constraint is the subject line, and it's sharper than anybody expects. Ours fits the product name into whatever is left of forty four characters once the rest of the subject is counted.

The rest of the subject is the words shipped and the release name. So every character you add to a release name takes one away from your own product's name.

Past thirty one characters of release name, the product name is cut to three characters and an ellipsis.

A release called The one where search finally works, which is a genuinely good name, arrives in an inbox as Nor… shipped The one where search finally works. The joke is on the product, not on the release.

The practical rule is that a release name is a label and not a sentence. Put the wit in the body, where there's room for it.

There's a third truncation, and it belongs to the in product strip, not the email. The post about changelog entries measures it, and the finding is that the first sentence is the entry.

What does each category oblige you to say?

Different things, and this is the part a template won't do for you.

A release note is filed under one of five categories on our side, which are new, improvement, fix, security and breaking change.

The categories are fixed, not free text, which matters more than it looks, because the first time somebody types Bugfix instead of Bug Fix a year of scannable history is gone. What matters more still is that each category carries a different obligation to the reader.

New owes the reader a reason to look. It's the only category where nothing is broken and nobody is waiting, so an entry that doesn't say what the thing is for is an entry nobody opens.

Improvement owes the reader the old behaviour. Without it the sentence is unreadable, because the reader can't tell whether this is a change or a description of something that was always true.

Fix owes the reader the symptom rather than the cause, and it owes them the scope. Fixed a bug in exports is worthless. Fixed the case where an export of more than a thousand rows lost its last column tells somebody whether they were affected, and that's the only question they have.

Security owes the reader three things and most notes carry one. What was exposed, whether they need to do anything, and whether it happened to them. A note saying only that a vulnerability was patched creates more support work than it prevents, because every reader has to ask.

Breaking change owes the reader a date and a replacement. Both, in the first sentence, before any explanation. This is the only category where the note has a job beyond being read, which is stopping somebody losing a day, and everything else about the writing is secondary to that.

What does a whole release look like written both ways?

Two versions of the same release below, because the failure compounds across an entry rather than living in a single sentence.

The version a team writes.

v3.2.0

Various improvements and bug fixes. Migrated the tag store to the new indexer. Added debounce to the search input. Deprecated the v2 API. Huge thanks to everybody for a big sprint.

Five sentences, four of which say nothing to anybody outside the company, and one of which is a breaking change sitting fourth in a list behind a thank you.

The same release, for the person receiving it.

The v2 API stops answering on 1 March

Everything it does is in v3 and the routes are the same shape, so most callers change one line. If you are on v2, this is the only thing in this release you need to read.

Two other things shipped. Tags now search instantly, including on boards with thousands of cards. And search no longer jumps around while you are still typing, which was the most reported annoyance on our board this quarter.

Same release, same work, same amount of writing. The differences are that the breaking change moved to the top and became a heading, the mechanisms became moments, and the thank you left. Nothing was invented and nothing was exaggerated.

What does a good one actually look like?

The same twelve above, and no.

Every pair in that table is a software release note, written the way an engineering team writes it and then written the way the customer needed it. A product release notes example is the second column.

The word product in front of it usually means the person asking wants the customer facing version, not the internal one, which is the whole distinction this post is built on.

Where the two genuinely differ is the audience for the detail. An engineering note can say the tag store moved to a new indexer and be useful, because the reader is somebody who will touch the indexer.

A software release notes example meant for customers has to say tags search instantly now, because the reader has no idea what an indexer is and never will.

Which are the best release notes examples, and what makes a good one?

The ones that would still be useful a month later to somebody who didn't follow the release.

That's the only test on this page that separates a good example from a tidy one. Run it over the twelve pairs and the winners are the entries that name the old behaviour, because a reader who arrives late can't judge a change without knowing what it replaced.

The best release notes examples are almost never the longest and are almost always the ones written as a comparison.

The second test is whether the entry survives being read by somebody who is annoyed.

A person arriving at a release note has often just been bitten by the thing you changed, and an entry full of adjectives about how excited the team is reads very differently in that mood than it did in the draft.

The four moves, ranked by what they buy

If you only change four things about how your team writes these, change these four, in this order.

Say what the old behaviour was. One extra clause, and it converts a statement into a comparison. A reader can't judge a change without knowing what it replaced, and this is the cheapest improvement available to anybody.

Lead with the noun the customer already uses. Not your component name. Not your ticket. The thing they would call it if they were complaining about it.

Put the breaking change in the first four words. Everything else on the list is about being read. This one is about not costing somebody a day.

Write the empty week. Publishing nothing shipped is worth more than publishing nothing, because it tells the reader the page is alive and that you're not hiding.

What can a release note not do?

Two things, and pretending otherwise is where teams lose trust.

It can't make a small change feel large. Adjectives are the tell. If the release genuinely is small, the honest entry is one line, and one honest line reads better than three paragraphs about how excited everybody is.

It can't reach people who never signed up to hear from you. On our side the announcement goes to the people whose own vote is in the release and who have an account with an address on it.

Anonymous voters get nothing, because there's nowhere to send it, and we say so rather than implying a broadcast. The anonymous voting page has the whole of that limit.

That's a smaller list than a mailing list and it's a better one. Every person on it asked for the specific thing you're announcing.

Where the note should live

On a page you own, with its own address, and in an email to the people who asked. Not one or the other.

The page is what search finds and what somebody links to eighteen months later when they're trying to work out when a behaviour changed. The email is what reaches the person who has stopped checking, and one written out in full, with the list it goes to, is on its own page.

The difference between the page and the document is worth ten minutes if you haven't thought about it, because the two words get used interchangeably and they're not the same object.

If you want a starting shape, not an argument, there's a template on this site in the five categories, free to copy and change, and what a release note is and who actually gets told you published one is the definition underneath all of this.

14 days, a card at signup, then $9 or $39 a month.