How to write a changelog nobody skips

A changelog is the only document most companies publish on a schedule, and it is almost always the worst one they write. Ours was, for years: a bulleted list of merged branch names with the word improvements doing a great deal of heavy lifting.

Three rules that fixed it

We wrote these down as an actual note pinned to the changelog page, which is how the agent learned them.

1. Lead with what somebody can now do. Not what we built — what changed for the person reading. "Notes now attach to any block" is a feature. "Refactored the note attachment layer" is a diary entry.
2. Name the thing you fixed, not the ticket. Nobody has your ticket numbers. Everybody has the bug.
3. If an entry needs a paragraph, give it a paragraph. The tyranny of the bullet is why changelogs read like inventory. Some releases deserve four sentences and a screenshot.

Letting the agent write it

Every entry on our changelog since 2.1 has been drafted by an agent from the pull requests that actually shipped, in the voice of the last ten entries, and then edited by a person for about ninety seconds.

It is better than what we wrote by hand, for a boring reason: it never runs out of care on a Friday. The last three bullets of a hand-written changelog are always worse than the first three, and the agent's are not.

The measurement

Open rate on the release email went from eleven per cent to thirty-four. Replies to it — actual humans writing back about a feature — went up by about six times. That is the whole argument for taking a document nobody reads seriously.