Write Release Notes Around What Users Can Now Do

A commit log is organized around implementation. Release notes should be organized around the user’s experience. “Refactored import handler” may describe real work while telling a customer almost nothing.

Start with the changed behavior and who will notice it. Then add technical detail only where it affects a decision or required action.

Describe the before and after

For a hypothetical import fix, write: “Rows with an empty optional phone field now import successfully.” That identifies the trigger and result. It is more useful than “improved import reliability.”

If the change is new functionality, describe the action users can take and where it is available. Avoid promising a broader capability than the release contains.

State the affected scope

Name the relevant plan, role, platform, or workflow if availability differs. A feature available to administrators should not be announced as if every user can access it.

For gradual rollout, explain the actual availability. Do not call a release complete merely because deployment has begun in one environment.

Surface required action

If users must update a setting, migrate an integration, or change a workflow, make that instruction easy to find. Link the detailed guide and include the relevant deadline only when it is established.

Keep compatibility information precise. A breaking change needs more than an enthusiastic description of the new behavior.

Separate fixes from known limits

Describe the bug that was fixed without implying that every related problem is resolved. If a limitation remains material to the announced workflow, mention it where users will encounter the claim.

For example, supporting one import format does not justify saying “import from any tool.” Concrete language prevents a release note from becoming a support problem.

Verify against the delivered version

Compare the note with the actual release scope and acceptance evidence. Remove items that were cut or are still behind an unavailable flag. Confirm links and navigation labels in the target version.

A useful final edit asks: could a user tell whether this change matters to them, find the changed behavior, and understand whether they need to do anything? If the answer is yes, the note has done its job.

Release notes do not need to celebrate every internal change. They need to make the shipped product easier to understand and use.