Your changelog has two audiences, and most release notes serve neither: users who want to know "what changed for me?", and support engineers who want to stop answering "is this bug fixed yet?". A commit-log dump answers neither.
The Three-Layer Format
- Headline - for everyone: "Faster exports and clearer billing errors"
- User-facing changes - for users: "Exports over 10,000 rows now stream instead of timing out."
-
Technical detail - for integrators: "Breaking:
GET /orderspagination default changes from 50 to 100."
The Grammar Problems Specific to Changelogs
- Mood mixing - "Fixed a crash" next to "Export speed improvements" next to "You can now filter by tag". Pick one voice per section.
- Jargon leakage - "Refactored the ingestion pipeline" means nothing to users. Translate to behavior: "CSV imports no longer stall on large files."
- Buried breaking changes - a schema change hidden at bullet #23 costs a week of support tickets.
A 15-Minute Release-Note Workflow
- Draft from the user's side: behavior change, not code change
- Run the prose through a code-aware grammar check - changelogs are full of
v2.4.1,--strict,apiKey, exactly the tokens generic checkers "correct". Lint skips them and fixes only the sentences. - Tone-check the voice - a tone analyzer catches drift from confident to apologetic across a long changelog
- Promote breaking changes to the top. Always.
Release notes are a support-cost lever disguised as a documentation chore.
👉 Try Lint free - 3 checks/day, no signup. BYOK: unlimited, $0.
Top comments (0)