Release Note

Deployments used to pass in silence. Putting what was built in front of users is a release, and with nothing attached to it, users find out on their own that a button they used yesterday is gone.

When that happens, the same event lands in three places at once. The user assumes something broke and files a ticket. Support can't tell whether it broke or changed, so they ask engineering. Engineering digs through commits to work out what actually shipped yesterday. Every quarter had a day where moving one part of a screen produced thirty support tickets — a day where the workload grows and nothing was fixed.

A release note turns that announcement into a fixed deliverable. The change gets written as something the user can now do rather than as the name of a feature, so people hear it before they have to ask. Twenty minutes of writing against thirty tickets is arithmetic that holds, which is how it became an internal rule rather than a nice habit. The cost is fixed and the savings scale with the number of users.

One release note carries five things.

1. The date and version. A change has to be pinned in time before a user can match it against something they experienced. Products built for developers print a version number; products for general users often print only the date, since a version they never see is noise to them.
2. Sections grouped by the kind of change. New features, improvements to existing ones, fixed defects, and things on the way out get separated. That last group is where a deprecation notice goes — the state of announcing in advance that something will be removed and discouraging its use.
3. One line per item. This is where the quality of the whole thing gets decided. "Search engine upgraded to v2" is the builder's sentence; "search now looks inside document text, not just titles" is the user's. The test is simple: write down what a reader can do differently afterwards. If nothing in the sentence answers that, the item probably belongs somewhere else.
4. Who is affected and what they need to do. Changes where an admin has to switch something on, or where an integration has to be edited, get called out separately. A change that breaks existing user code is a breaking change, and burying one in a sub-bullet doesn't count as having announced it.
5. Where to read more. A help article address and a route for questions sit at the end, so a short note can stay short without stranding anyone.

Length follows the size of the change. Two bug fixes make three lines; a pricing change fills a screen with a screenshot and an example. Where a team grades announcement reach with something like a launch tier, that grade usually settles the length for you, which spares the writer from re-arguing the question every release.

The writer is usually the product manager, and on larger launches a product marketing manager takes the wording. Either way, engineering checks the facts, because only the people who built it know what actually shipped and what slipped out of this release. Support reads it before it goes out too — they are the best judge of whether a sentence will raise the ticket count or lower it, and they have the week's ticket queue in front of them while they read.

Readers split into three groups. First, the people using the product daily. They check whether the screens they work in changed and then leave, so a long run of items that don't apply to them means the rest goes unread. Second, the team's administrators. They look for anything touching permissions, billing or security, and decide whether their own team needs a separate heads-up. Third, sales and support inside the company. They read it to answer questions customers are about to ask, which makes them the most thorough audience of the three; wherever an internal reader comes back with a question, customers get stuck in the same spot.

Serving all three in one document comes down to order. Put the high-impact changes at the top and the internal improvements at the bottom, and each group can stop reading at the point where it stops mattering to them. Nobody has to read the whole thing for the whole thing to work.

"Let's leave this one out of the notes. It's an internal refactor with nothing for users to see."

Applying the rule that nothing goes in unless something changes for the reader.

"This one gets notes only. No company-wide email."

It's worth publishing but not worth pushing into anyone's inbox.

"A customer wrote in after reading the notes. That sentence created the confusion."

The announcement raised the ticket count instead of lowering it, so the wording needs fixing.

When Pagedeck added expiry dates to shared document links, the first draft read "applied an expiry policy to shared links." Mia rewrote it as "shared links can now be set to 7 days, 30 days or no expiry, and the default is 30 days." Administrators needed to know when their existing links would stop working before anything else in the note mattered.

Theo confirmed that links created before the change would keep working as they were, and that line went in alongside. Sofia copied the item as it stood and sent it to her accounts ahead of the general announcement, which is the usual sign that a note was written for the right reader.

The most common mistake is treating it as reformatted engineering history. Both list what changed, so tidying up a commit log looks like most of the work. The audiences are different, though. A commit log is read by someone who knows the code and wants to find what got touched; a release note is read by someone who doesn't and wants to know whether their own work changes. Notes written in the first voice produce no decision on the reading end, and the question comes back as a support ticket anyway.

Believing that more complete is better is the other one. It looks conscientious, but reading time is fixed. Put a billing change twelve lines below a run of internal improvements and that change has effectively not been communicated. The real work in this document isn't choosing what to include — it's choosing what goes on top.