Telling people what changed.
WHY THEY MATTER
Users encounter changes without warning and they must understand what happened.
WHAT TO INCLUDE
What changed Why, where it helps What users must do What breaks What was fixed Known issues
WHY WHAT USERS MUST DO
It is the only part many readers need.
WHAT TO PUT FIRST
Anything requiring action.
WHAT TO MARK CLEARLY
Changes that break existing use Changes that require configuration Changes to behaviour people depend on
WHY BREAKING CHANGES
Users discovering them in production is the worst outcome.
WHAT TO PROVIDE
How to adapt, specifically.
WHAT TO AVOID
Internal terminology Change lists that mean nothing to users Omitting removals Describing fixes without describing the symptom
WHY THE SYMPTOM
Users recognise the problem they experienced, not the internal cause.
WHAT TO WRITE
What was wrong from the user's perspective, and that it is resolved.
WHAT TO ESTABLISH ABOUT KNOWN ISSUES
That they are stated.
WHY
Users discover them, and prior disclosure preserves confidence.
WHAT TO ESTABLISH ABOUT TIMING
Notice before a change, where it affects users.
WHY
Advance notice allows preparation; simultaneous notice does not.
WHAT TO PROVIDE FOR SIGNIFICANT CHANGES
More than a release note: direct communication.
WHAT TO ARCHIVE
Previous release notes.
WHY
Users upgrading across several versions need the intervening changes.
WHAT TO ESTABLISH
Consistent format and place.
