The best release notes are not a summary of everything that changed. They are a trace of the decisions that matter to the person reading them a week later.
In practice, that means separating signal from motion:
- what changed in the public shape of the system,
- what changed in the operating path,
- what changed in the failure model.
When those three are explicit, a release log becomes a small operational artifact instead of a marketing recap.
Keep the audience narrow
I write for the person who has to answer a question at 9:00 a.m. with only the repo and the deploy log in front of them. That audience does not need adjectives. It needs names, paths, and a clean sequence.
Prefer one source of truth
If a publishing pipeline writes content into one repository and deploys from another, the public URL, content directory, and deployment target must all be named in one place. Split ownership is fine. Split knowledge is not.
End with a stable sentence
My favorite release note ends with a sentence that can be copied into an incident review later:
The deployment path is now explicit, content lives in the source repo, and the public site is rebuilt from the same static output every time.