Why are release notes so often vague or wrong?
Release notes go wrong because they are written from ticket titles at the last minute, by someone who was not in every conversation, for an audience nobody defined. The result is either a list of internal jargon or a cheerful summary that promises more than shipped.
Picture a fictional 15-person software company, Tallyhop, which makes a booking tool for fitness studios. The product manager, Dev, has this list of merged tickets for version 4.3: 'TH-412 fix tz bug recurring classes across DST. TH-398 waitlist auto-promote (flag waitlist_v2, 20% rollout). TH-405 refactor payments service to new SDK. TH-410 rename Members to Clients in nav. TH-401 deprecate CSV export v1, removal 1 Dec. TH-415 calendar load perf.'
Three different groups need to hear about this release. Studio owners care about the waitlist, the renamed menu and the export removal. Support needs to know who has the waitlist and what to say when someone cannot find Members. Developers using the export need the exact date and the replacement.
How do you write release notes step by step?
Write release notes by first confirming what shipped and to whom, then sorting changes into fixed categories, then writing a separate version for each audience that leads with the effect on the reader and any action they must take. AI handles the sorting and rewording well; you supply the facts it cannot see in ticket titles.
1. Confirm what shipped
Check each ticket against the release: merged but behind a flag, partly rolled out or fully live. A 20% rollout is not 'now available'.
2. Sort into categories
New, improved, fixed, changed, deprecated or removed, and known issues. Readers scan for the category that affects them.
3. Decide what each audience sees
Customers rarely need internal refactors. Support needs rollout details. Developers need dates, versions and replacements.
4. Lead with the effect
'Recurring classes now keep the right time when the clocks change' beats 'Fixed timezone bug'.
5. State actions and dates plainly
Anything the reader must do, and by when, goes first and in its own line.
6. Number the release consistently
If you use semantic versioning, the first number signals incompatible changes, the second backward-compatible features and the third backward-compatible fixes, so readers can judge risk at a glance.
What does a weak and an improved AI release note look like?
Weak prompt: 'Write release notes from these tickets.' Typical result: 'Version 4.3 is packed with improvements! Waitlists now automatically promote clients for everyone. We've rebuilt payments for faster, more secure checkout. Members is now Clients. Calendar loads faster.' Three problems: the waitlist reaches only some studios, the payments refactor made no promise about speed or security, and the CSV export removal, the one change that needs action, is missing.
Improved prompt: 'Write customer release notes for studio owners from the tickets below. Categories: new, improved, fixed, removed. Include only changes a studio owner can see. TH-398 is available to some studios only, so say it is rolling out gradually. TH-405 is internal; leave it out. Put the CSV export removal first with its date and what to use instead: [replacement]. Do not describe benefits that are not stated in the ticket. Use plain words and no ticket numbers.'
The improved result opens with 'Action needed: the original CSV export will be removed on 1 December. Use [replacement] instead.' It then says waitlist auto-promotion is rolling out gradually, explains the Clients rename in one line and describes the daylight saving fix in terms of class times. A second prompt produces the support version, with the flag name and rollout percentage, and a third produces a short developer changelog.
How do you check release notes for accuracy?
Check release notes by tracing every sentence back to a ticket and asking the engineer or product owner to confirm anything about availability, dates or behaviour. A release note is a promise to customers, so an unchecked line becomes a support ticket.
Availability
Is each feature live for everyone, a subset or nobody yet? Match the wording to the rollout.
Invented benefits
Delete words such as 'faster', 'more secure' or 'easier' unless someone measured or decided them.
Actions and dates
Confirm removal dates and replacements with the owner, and check the date format your readers use.
Names on screen
Feature and menu names must match the product exactly, especially after a rename.
What are the common mistakes with AI release notes?
The most common mistake is publishing one version for everyone, which buries the action customers need and exposes internal detail they do not. Others: announcing flagged features as live, letting the tool add marketing claims, hiding a removal under 'improvements', leaving ticket codes in customer notes and pasting unreleased roadmap items or security fix details into a public tool. Security fixes in particular should follow your team's disclosure rules before they appear anywhere.
Where does this lesson sit in the Tosheo.ai catalogue?
Release notes is a Practitioner lesson in the AI for Product category, next to interview synthesis, specs and user stories, feedback analysis, competitor research and prioritisation trade-offs. The full list is on the AI training for product teams page. In the hands-on task you get a fictional ticket list and write two versions for two audiences; the rubric checks availability wording, actions, invented claims and audience fit.