← All posts
One year of release notes
What a year of weekly releases taught us about writing changes people read.
FIG. 52
A year of issues, tied up.
Company
By D. Sample
Go to market
7
min
Sample post
Every name, figure and line here is sample copy.
We have shipped a release every week for a year. Each one came with notes, and for most of the year those notes were read by fewer people than wrote them. Here is what we changed.
Lead with what changed for the reader
Our early notes described what we did. Readers wanted to know what had changed for them. Now every note starts with the effect, then the cause, in one sentence each.
Three rules we kept
One change per line, so a reader can scan the list in seconds.
No adjectives. A faster search is faster; it does not need to be dramatically faster.
Every breaking change links to the page that explains it.
The changelog on this site follows those rules. Every entry in it is sample content.
Next post
Reviewing an agent's pull request →
New posts by email.
One email per post. Unsubscribe at any time. See the privacy notice.
