Wall.fm Blog · building communities ✦

Shipping

How to write release notes: start with what people can do now.

Most users skim release notes in seconds. Learning how to write release notes well means putting the change they will notice at the top, in plain words.

Big launches need a different shape again: a “2.0 is here” announcement explains why, not just what.

How to write release notes: the basics

Four habits.

  1. Lead with benefits. “You can now reply by email” beats “added SMTP reply handler”.
  2. Group by type. Added, Changed, Fixed, Removed: the Keep a Changelog convention.
  3. Date and number every release. Semantic Versioning uses MAJOR.MINOR.PATCH.
  4. Link to help. One link per big change.

The major-version announcement

When it is a 2.0.

Under Semantic Versioning, a major version signals changes that are not backwards compatible. For users, say what moved, what is new and what they need to do, in that order.

A 2.0 announcement outline
SectionContent
HeadlineVersion 2.0 is here
Whythe problem the release solves
Top three changesone screenshot each
What you need to donothing, or a short list

Sources and further reading

Where the facts on this page come from.