By Harpal Singh · · 4 min read
Release notes are the only documentation most users ever read about a new version, and most of them are written for the wrong reader. "Refactored the sync module" is a true sentence and a useless one. What the user wants to know is whether the thing that annoyed them last week is fixed, and whether there is anything new they should try.
This guide gives a template, a worked set of sample release notes and the cases where a short recording does more than another paragraph.
What should release notes contain?
Keep it to what a user needs to decide whether to care.
- The version and the date, so the note can be placed in time.
- A one-line headline, the thing most users will care about.
- What is new, each item in one or two sentences, in the user's terms.
- What is fixed, named by the symptom the user saw, not the cause.
- What has changed, anything that behaves differently and might surprise someone.
- What to do, only if there is an action: update a setting, reinstall, re-authorise.
Leave out the internal refactor, the dependency bumps and the ticket numbers unless your audience is other developers.
What does a release notes template look like?
Version 2.4 — 14 October
Headline: Reminders now send themselves.
New
- Automatic reminders. Set a schedule once and overdue invoices get nudged without you.
- Faster search. Results appear as you type.
Fixed
- Invoices with a long client name no longer overflow the page.
- The export button works again on the archive view.
Changed
- The default due date is now 30 days, not 14. Existing invoices are not affected.
Action
- None. Update from Settings > About.
Everything above is in the user's words, ordered by how much it matters, and short enough to read in half a minute.
What does a software release notes example look like?
Here are sample software release notes for a made-up desktop app, a software release notes example you can adapt, so you can see the tone. The product and details are invented.
Version 1.8.0 — 6 March
Highlights. Projects open faster, and you can now export to PDF.
New. Export any project to PDF from File > Export. Pages keep your layout and fonts.
Improved. Large projects open in a fraction of the previous time. The sidebar now remembers which folders you had expanded.
Fixed. Undo no longer skips a step after pasting. Dark mode no longer shows white borders around images.
Known issue. Exporting very large projects can take several minutes; we are working on it.
Notice the shape: a headline, three sections, one honest known issue. Naming a known issue builds more trust than leaving it out.
What is the difference between release notes and a changelog?
A changelog is a complete record, in date order, kept for completeness. Release notes are a curated summary of one release, written for users. Small products often combine them in one dated list, and that works if the most important change comes first in each entry. ReScreen's own changelog is written that way: dated, with what the application does after each release rather than a list of tickets.
How should you write them?
- Write for the user, not the team. Describe the symptom or the benefit, not the code.
- Lead with the biggest change. Not the first one you merged.
- Be specific. "Improved performance" says nothing; "projects open in half the time" does.
- Keep every item to one or two sentences.
- Say what is not fixed, if users will hit it.
- Date every entry. A note without a date cannot be trusted.
When does a short video help?
When the change is easier to see than to describe. A new interaction, a changed layout, a workflow that is now shorter: a thirty to sixty second recording shows it in less time than a paragraph and answers the "wait, where did it go" question before it is asked.
Record the actual change in the real product, at a resolution that keeps the text readable, with the zoom following your clicks so the viewer can see what you pressed. Keep the written note complete on its own, and link the recording beside it. How to record a software demo covers the recording, and the product demo video feature lists the preset. Developers often attach the same recording to the pull request, and screen recording for developers explains how.
Where do release notes belong?
Where users already look: in the app after an update, on a changelog page and in the email that announces the version. An in-app note that links to the full page covers both the casual reader and the one who wants detail.
How often should you publish them?
With every release a user can see. Writing a note for a patch that fixes one thing takes two minutes and tells the person who reported it that it is done, which is worth the two minutes. Customer onboarding videos are the longer-lived counterpart for what a new user needs to learn first.
If you want to record the next change instead of describing it, see the screen recording feature and download ReScreen for macOS.
Filed under
