Write every release note with the same four fields, in the same order: what changed, who’s affected, what you need to do, where to get help. Keep the format fixed so people learn where to look and can skim it.
The usual release note is a ticket dump. It lists what the team did, in the team’s words, and leaves each reader to work out what it means for them. Expertise makes people worse at predicting what non-experts will understand, and trying to be clearer does not fix that. A template helps. A long, accurate, technical note can also read as a brush-off, even when it was written in good faith.
The four fields
| Field | What goes in it |
|---|---|
| What changed | The outcome, first, in the reader’s words. If the change takes something away, say so here, before readers discover it themselves. |
| Who’s affected | The roles or teams, named. If two groups are affected differently, each gets its own short note with only what matters for their role. |
| What you need to do | The action and the date. |
| Where to get help | A named person, the one channel requests go through, or office hours. |
How it was built, the root cause and the ticket numbers are an appendix. Link them underneath for the people who want to dig.
An example
Before, straight from the tracker:
FIN-482 Resolve approver from manager field in routing service
FIN-377 Remove approver dropdown from submit form
FIN-490 Backfill approver on open drafts
After:
Expense reports now go straight to your manager
What changed
From Monday, an expense report goes to your manager for approval as soon
as you submit it. The approver list on the submit screen is gone, so you
can no longer send a report to someone else.
Who's affected
Everyone who submits or approves expense reports. Reports you have
already submitted are not affected.
What you need to do
Before Monday, open your profile and check that the manager shown is
correct. If it is not, tell the finance systems team.
Where to get help
Post in the finance systems channel, or come to office hours on Thursday
at 2pm.
The same three tickets are behind both versions. The second one starts with the outcome, names the thing people are losing, and gives one action with a date.
Sending it
- For a change that affects how people work, send the first note no later than two weeks ahead, then send it again. Repeating it feels excessive to the team that has lived with the change for a month. For the reader it is new every time.
- One post in one channel reaches a fraction of the people who need it. Plan on more than one channel and more than one pass.
- Put the note in the definition of done, so it is built into the release instead of added afterwards.
