Design Release Notes and Change Communication
Foundations & Process · process, microcopy, trust
Updated 2026-07-28
- Write for the person affected, not for the team that shipped it. Internal component names and ticket numbers belong in the commit, not in the note.
- Lead with what someone can now do, or no longer has to do. A feature described by its mechanism is a feature nobody adopts.
- Separate the three kinds of change, because they need different attention:
- New capabilities, which can be explored later.
- Changes to existing behaviour, which need to be read now.
- Fixes, which mostly need to be findable by the people who reported them.
- Announce breaking changes before they happen, not in the note that accompanies them.
- Put the announcement where the change is. A note in the changelog is invisible, and a one-time marker on the feature itself is not.
- Keep it proportional. A small improvement does not need a modal, and a workflow that moved does.
- Tell the people who asked. Closing the loop with the person who reported a bug is the cheapest goodwill in any product.
- Keep an archive that is searchable and dated, because support and customers both need to know when something changed.
- Never let the announcement be the first time a paying customer hears that something they relied on is gone.
A changelog nobody reads is still worth keeping, and a change nobody was told about is a support ticket you scheduled in advance.
Related guides
UX Handbook