Skip to content
Back to blog
Guides

Writing release notes your customers will actually read

A changelog is a promise that you noticed what you shipped. Five small rules for turning a list of commits into something worth opening.

Hannah Lindqvist

Editor in Chief

Published
Reading time
1 min
The nib of a fountain pen resting on handwritten notes in looping script
Photograph via Unsplash

Most release notes are written for the people who shipped the release. They list tickets, mention internals and lean heavily on the passive voice. A customer opening them is looking for one thing: what does this mean for me?

Five rules we follow

  1. Lead with the benefit. You can now export any report as CSV, not Added CSV export endpoint.
  2. Write for one person. Imagine the customer who asked for it, and tell them it's done.
  3. Show, don't describe. A ten-second screen capture beats a paragraph.
  4. Say what changed, not what you did. Nobody cares that you refactored the settings page.
  5. Be plain about breaking changes. Put them at the top, with a date and a link to help.
A hand writing with a blue pen on paper beside a coffee cup and a laptop
We draft release notes on paper first. It keeps them shorter.Photograph via Unsplash

The test

Before publishing, read each line aloud and ask: would someone who has never heard of this feature understand why it matters? If not, rewrite it or cut it.

Written by

Hannah Lindqvist

Editor in Chief

Hannah edits the Journal and writes about the habits that make small teams effective. Before Leaf she ran the docs team at a developer-tools company.

Keep reading

All stories