Oct 13, 2023 • CRAFT
Most release notes get written in the last ten minutes before a deploy, and it shows. They get skimmed, or skipped, and then the same question turns up in support a week later.
Here is what separates the ones people read.
"Refactored the notification service" tells a customer nothing. "Notifications now arrive in a few seconds instead of on a five-minute delay" tells them whether to care.
The test is simple. Could someone who has never seen your codebase work out whether this affects them? If not, rewrite the line or cut it.
You get a headline and maybe two lines of attention. If a release has one new feature and eleven fixes, the feature goes on top and the fixes go in a list underneath.
Strict chronological order is a changelog habit. Release notes are edited.
One clause usually does it. "You can now filter by status, so you can pull up everything still in review without scrolling."
The reason does not need a paragraph. It needs to exist.
A screenshot or a five-second GIF beats three paragraphs describing where a button moved. This matters most for layout changes, where the fastest explanation of a new screen is the new screen.
"Various improvements and bug fixes" is a wasted line. If you fixed something people could see was broken, say which thing. The users who hit it are glad it was acknowledged, and everyone else skims past in a second.
If something is still broken, say that too, along with what you are doing about it. It costs nothing and buys a lot of patience.
A complicated change does not need a full tutorial inside the release note. Two sentences and a link to the docs respects people who only wanted to know it exists, and serves the ones who want the detail.
Address the reader directly. "You can now" reads better than "users are now able to." A thank-you at the end of a big release is fine. Keep the ceremony to a sentence or two, including milestone announcements, which are worth mentioning but are not what people opened the page for.
Notes that appear whenever someone remembers to write them stop being a thing people check. Weekly, biweekly, per tag, whatever matches how you ship. The regularity matters more than the interval.
If you change one thing on this list, change the first one. Write what the customer will notice, in the words they would use for it. Everything else follows from that.
Want to see Onset in action? Try it for free today. No credit card required.
Get startedWe use cookies to understand how you use our site and to improve your experience. Analytics cookies are only set once you accept. See our Privacy Policy for details.
