| name | Release Notes |
| description | Turn a release into notes a customer can act on, without leaking internals or overstating the change. |
| category | Go-to-Market |
Release Notes
Write what changed for the person using the product. Not what was merged, not
what the team is proud of.
When to use
- A
releases row moves to rolling out.
- A customer asks what is new, or what they are running.
Steps
- Read the release row, not the commit log.
contents is already grouped
the way customers experience the change; the commit log is grouped the way
the work happened.
- Sort by who it affects. Anything that changes existing behaviour comes
first, then new capability, then fixes. Something a customer must do comes
above all of it, labelled as such.
- Write each line as an outcome. "Exports now include archived records" —
not "fixed export filter predicate".
- Name the breaking changes plainly, with what to do about each. A breaking
change described gently is one somebody discovers in production.
- Check against the docs. Anything described here that the docs still
describe the old way is a doc task, opened now.
- Leave internals out. Service names, ticket numbers and internal codenames
mean nothing outside and sometimes mean too much.
Output
Release notes ready to publish, ordered action-required → changed → new →
fixed, plus any doc tasks the pass turned up. Publishing is a person's call.
