# 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. Parent: [Writing and Documentation](https://llms-explorer.com/tree/writing-and-documentation/) · 11 facets · 44 facts · page: https://llms-explorer.com/tree/changelogs-for-humans/ ## 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: `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. — 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? — 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. — source: `https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#how-to-use-this-skill` - Lead with the outcome, not the mechanism. — 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. — source: `https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#how-to-use-this-skill` - Decide on version-number visibility. — 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. — 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. — source: `https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#3-benefit-led-language` - Cut entries with no user-visible effect. — 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. — source: `https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#3-benefit-led-language` - Keep one sentence per atom. — source: `https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#3-benefit-led-language` ## 4. Visuals — when, where, what - Image craft checklist: — 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. — 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. — 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. — source: `https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#4-visuals-when-where-what` - GIFs: under 5 MB, autoplay-on, loop. — 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. — 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. — 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. — 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. — 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. — source: `https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#anti-patterns` - The screenshot of nothing. Always shoot with realistic data. — 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. — source: `https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#anti-patterns` ## References - Linear changelog - linear.app/changelog — source: `https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#references` - Vercel changelog - vercel.com/changelog — source: `https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#references` - Stripe Blog: Changelog - stripe.com/blog/changelog — source: `https://llms-explorer.com/sources/mdb-context-hub/changelogs-for-humans/#references` - Mailchimp "What's New" - mailchimp.com/whats-new — 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](https://llms-explorer.com/tree/changelogs-for-humans/) *(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](https://llms-explorer.com/tree/changelogs-for-humans/) *(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](https://llms-explorer.com/tree/changelogs-for-humans/) *(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](https://llms-explorer.com/tree/changelogs-for-humans/) *(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](https://llms-explorer.com/tree/changelogs-for-humans/) *(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](https://llms-explorer.com/tree/changelogs-for-humans/) *(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](https://llms-explorer.com/tree/changelogs-for-humans/) *(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](https://llms-explorer.com/tree/changelogs-for-humans/) *(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](https://llms-explorer.com/tree/changelogs-for-humans/) *(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](https://llms-explorer.com/tree/changelogs-for-humans/) *(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](https://llms-explorer.com/tree/changelogs-for-humans/) *(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](https://llms-explorer.com/tree/changelogs-for-humans/) *(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](https://llms-explorer.com/tree/changelogs-for-humans/) *(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](https://llms-explorer.com/tree/changelogs-for-humans/) *(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](https://llms-explorer.com/tree/changelogs-for-humans/) *(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](https://llms-explorer.com/tree/changelogs-for-humans/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)*