Changelogs for Humans

Parent: Writing and Documentation · researched 2026-05-29T19:22:28.475Z· 7 sources · 9 concepts · skill changelogs-for-humans

Reference for user-facing changelog craft: the public-product update feed read by end users, not the engineering changelog read by integrators.

Changelogs for Humans

Reference for user-facing changelog craft: the public-product update feed read by end users, not the engineering changelog read by integrators. [source]

How to use this skill

Confirm the audience is the end user, not the developer/integrator. [source]
Identify the surface. Public changelog feed / monthly digest email / in-product "What's New" panel? [source]
Group by user benefit, not by file tree. [source]
Lead with the outcome, not the mechanism. [source]
Decide on visual treatment. Major UI changes get a screenshot or GIF. [source]
Decide on version-number visibility. [source]

3. Benefit-led language

Replace internal nouns with user verbs. [source]
Quantify when honest. "3x faster" is honest if measured. [source]
Cut entries with no user-visible effect. [source]
Name the bug by the symptom, not the cause. [source]
Keep one sentence per atom. [source]

4. Visuals — when, where, what

Image craft checklist: [source]
Real product data wherever the user's eye lands. [source]
Dark mode if your product has dark mode. [source]
Crop tightly. [source]
Alt text describes the change, not the chrome. [source]
GIFs: under 5 MB, autoplay-on, loop. [source]

5. Version numbers — hide, downplay, or omit

Linear, Vercel, GitHub, Notion: no version numbers in the user changelog. The date is the version. [source]

Anti-Patterns

The version-number-only changelog. "v1.42.0 - bug fixes and improvements." This is not a changelog. [source]
The "we're excited to announce" opener. Cut. Open with the change. [source]
The commit-log dump. Pasting git log --oneline into a webpage. [source]
The "improved performance" non-entry. Either quantify it or omit it. [source]
The screenshot of nothing. Always shoot with realistic data. [source]
The "internal upgrade" entry. "We upgraded our database to version 16." The user does not care. [source]

References

Linear changelog - linear.app/changelog [source]
Vercel changelog - vercel.com/changelog [source]
Stripe Blog: Changelog - stripe.com/blog/changelog [source]
Mailchimp "What's New" - mailchimp.com/whats-new [source]

Children

Benefit-Led Language (not feature-list) (frontier)
Skip-the-Version-Numbers Approach (frontier)
Screenshots and GIFs for UI Changes (frontier)
Grouping by Audience Benefit (frontier)
Linear/Stripe/Vercel/Notion Changelog Pattern (frontier)
RSS-Feed Friendliness (frontier)
Monthly Digest Patterns (frontier)
Mailchimp What's New Email Format (frontier)
ChangeKeep Readable Conventions (frontier)

Frontier under this node: Benefit-Led Language (not feature-list), ChangeKeep Readable Conventions, Grouping by Audience Benefit, Linear/Stripe/Vercel/Notion Changelog Pattern, Mailchimp What's New Email Format, Monthly Digest Patterns, RSS-Feed Friendliness, Screenshots and GIFs for UI Changes, Skip-the-Version-Numbers Approach

← the whole tree · 3D view· how to read this page