Changelogs for Humans
Parent: Writing and Documentation · Published reference · snapshot 2026-09-08 · skill technical-writing-craft/references/changelogs-for-humans.md
↓ Facts as markdownall context files
Reference for user-facing changelog craft: the public-product update feed read by end users, not the engineering changelog read by integrators.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#changelogs-for-humans]
How to use this skill
- Confirm the audience is the end user, not the developer/integrator. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#how-to-use-this-skill]
- Identify the surface. Public changelog feed / monthly digest email / in-product "What's New" panel? [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#how-to-use-this-skill]
- Group by user benefit, not by file tree. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#how-to-use-this-skill]
- Lead with the outcome, not the mechanism. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#how-to-use-this-skill]
- Decide on visual treatment. Major UI changes get a screenshot or GIF. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#how-to-use-this-skill]
- Decide on version-number visibility. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#how-to-use-this-skill]
3. Benefit-led language
- Replace internal nouns with user verbs. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#3-benefit-led-language]
- Quantify when honest. "3x faster" is honest if measured. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#3-benefit-led-language]
- Cut entries with no user-visible effect. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#3-benefit-led-language]
- Name the bug by the symptom, not the cause. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#3-benefit-led-language]
- Keep one sentence per atom. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#3-benefit-led-language]
4. Visuals — when, where, what
- Image craft checklist: [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#4-visuals-when-where-what]
- Real product data wherever the user's eye lands. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#4-visuals-when-where-what]
- Dark mode if your product has dark mode. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#4-visuals-when-where-what]
- Alt text describes the change, not the chrome. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#4-visuals-when-where-what]
- GIFs: under 5 MB, autoplay-on, loop. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#4-visuals-when-where-what]
5. Version numbers — hide, downplay, or omit
- Linear, Vercel, GitHub, Notion: no version numbers in the user changelog. The date is the version. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#5-version-numbers-hide-downplay-or-omit]
Anti-Patterns
- The version-number-only changelog. "v1.42.0 - bug fixes and improvements." This is not a changelog. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#anti-patterns]
- The "we're excited to announce" opener. Cut. Open with the change. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#anti-patterns]
- The commit-log dump. Pasting git log --oneline into a webpage. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#anti-patterns]
- The "improved performance" non-entry. Either quantify it or omit it. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#anti-patterns]
- The screenshot of nothing. Always shoot with realistic data. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#anti-patterns]
- The "internal upgrade" entry. "We upgraded our database to version 16." The user does not care. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#anti-patterns]
References
- Linear changelog - linear.app/changelog [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#references]
- Vercel changelog - vercel.com/changelog [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#references]
- Stripe Blog: Changelog - stripe.com/blog/changelog [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#references]
- Mailchimp "What's New" - mailchimp.com/whats-new [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#references]
Where this helps
- Writing the public What's New feed or changelog email that end users read, as distinct from the engineering changelog that integrators and developers read. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- A product update needs to be described in terms of what the user can now do, not which internal file or module changed. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Deciding whether to show a visual for a changelog entry, and where real product data, not placeholder screenshots, belongs in that image. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Deciding how much to foreground version numbers — some products such as Linear, Vercel, GitHub, and Notion drop them entirely from the user-facing changelog and let the date carry that role. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
How to apply this
- Confirm the audience before drafting; a user-facing changelog and a developer or integrator changelog are different documents with different vocabulary, even for the same underlying change. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Group entries by user benefit rather than by file tree or internal module boundaries, since the reader doesn't know or care which internal system changed. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Replace internal nouns with user verbs, and quantify claims like “3x faster” only when the number is actually measured, not aspirational. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Cut any entry that has no user-visible effect; an internal refactor or dependency bump belongs in the engineering changelog, not the human-facing one. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Common mistakes
- Publishing a version-number-only entry, “v1.42.0, bug fixes and improvements,” that tells the reader nothing about what actually changed. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Opening with “we're excited to announce” instead of leading with the change itself, which wastes the reader's attention before the actual news. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Pasting a raw commit-log dump into a public-facing changelog page instead of translating it into user-benefit language. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Including entries with zero user-visible effect, which trains readers to skim past the whole feed because most entries don't matter to them. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Known issues
- A user-facing changelog necessarily loses precision that a developer changelog keeps; deciding what to cut without misleading the reader is a judgment call, not a mechanical filter. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Dropping version numbers entirely, as Linear, Vercel, GitHub, and Notion do, works well for a continuously-deployed product but can leave integrators or support teams without a stable reference point to cite in a ticket. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Quantified claims like “3x faster” require an actual measurement behind them; without one, honest-but-vague framing is the correct fallback, not a fabricated number. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Visuals need to reflect real product data at the point the user's eye lands, including dark mode support, which means a changelog image goes stale the moment the UI it depicts changes. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
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