Docs vs changelog: what each one is for (and how to keep them in sync)

Documentation and a changelog look like siblings — both are prose about your product, often written by the same person, sometimes living on the same site. But they answer opposite questions. Docs answer “how does it work now?” — they describe the present, and get edited in place as the present changes. A changelog answers “what changed, and when?” — it’s an append-only record of the past, and its entries keep their meaning forever.

Products need both, because readers arrive in two modes: the learner, who has never seen the feature and wants the current truth with no history attached, and the returner, who knew how it worked last month and wants the diff. Teams that run only docs strand the returner; teams that run only a changelog strand the learner. This guide is about the boundary between the two documents — what belongs where, and the small set of rules that keeps them in sync instead of quietly contradicting each other.

Two documents, two tenses

The clean way to hold the distinction: docs are a snapshot, the changelog is a ledger.

  • Docs are edited in place. When behavior changes, the old sentence is wrong and you delete it. A docs page has no obligation to its own history — its only job is to be true today. (Git remembers the old text; readers shouldn’t have to.)
  • The changelog is append-only. An entry describes the world at the moment it shipped, and stays correct as a historical statement even after three more releases change everything again. You fix typos and broken links in old entries; you don’t rewrite what they announced.

This is why neither can do the other’s job. Learn a product from its changelog and you’re doing archaeology — replaying years of diffs to reconstruct the present state, with no way to know which entries were later superseded. Track a product through its docs and you get silence — the page changed under you some Tuesday, and nothing tells you that the default you memorized in March stopped being the default in June. A “Last updated” timestamp doesn’t fix this: it tells returners that something changed, but not what, so it generates anxiety instead of information.

The ship-together rule

Everything about keeping the two in sync reduces to one rule: a release that changes behavior touches both documents, in the same release. The docs edit makes the present true again; the changelog entry tells returners the present moved. One change, two writes — the same discipline as updating code and tests together.

In practice that means the definition of done for a behavior-changing PR includes the docs edit and the changelog draft. Teams that write the entry in the release pipeline or hold drafts until ship day already have half of this; the docs edit rides the same train. The failure smell is a release thread where someone asks “did the docs get updated?” after the announcement went out.

The rule also tells you what doesn’t need a changelog entry: docs-only changes. Typo fixes, clearer wording, a new tutorial — edit freely, announce nothing. One exception worth respecting: when a docs correction changes what users believe (“the docs said retries were automatic; they never were”), treat it like a behavior change and write the entry. From the reader’s side, the documented behavior was the behavior — correcting the claim is news, even though no code shipped.

Link both ways

The sync rule keeps the two documents consistent. Bidirectional links make the consistency visible, and each direction serves a different reader:

  • Changelog entry → docs. The entry announces the change and links to the exact page — ideally the exact section — that now documents it. The entry is the news; the docs are the manual. Don’t make readers hunt for where the new feature is explained. This also enforces honesty: if there’s no docs page to link, the feature shipped undocumented and the entry just told everyone.
  • Docs → changelog entry. Reference pages gain a small “Changed in v2.3” note linking to the entry’s permalink. It answers the returner’s quiet questions — was this always true? since when? — right where the doubt occurs, and gives them the full story one click away. This is the single cheapest trust feature docs can have, and it’s why stable per-entry permalinks matter: a docs page can’t cite an entry that has no URL.

Keep the annotations pruned. “Changed in” earns its place for a version or two, while returners from the old world are still arriving; a reference page wearing nine of them is a history lesson pretending to be a manual, and is due a clean rewrite. (Libraries are the exception — “added in v3.1” stays useful as long as people run v3.0, which is why API reference generators emit it forever.)

When history belongs inside the docs: versioning

There’s one case where docs legitimately carry history: versioned docs, where readers pick v2 or v3 from a dropdown and each is a complete snapshot. It’s the right call exactly when old versions are alive — libraries and self-hosted software with long-lived majors, where a team pinned to v2 for another year needs v2’s docs, not a manual for software they don’t run. (Release notes for libraries covers that world’s changelog side.)

For SaaS and anything hosted, versioned docs are a trap. There is one live version; snapshots of docs for versions nobody can run are pure maintenance debt, and every fix now lands N times or silently doesn’t. The changelog carries the history; the docs stay singular and current. If your API uses dated versions Stripe-style, document the current behavior per version pointer, not a full docs fork per date.

The overlap case that trips teams up: migration guides. A migration guide is task documentation — “how do I get from v2 to v3” — so it lives in the docs, gets maintained as errata surface, and survives as long as v2 users exist. The breaking-change entry announces the change, carries the dates and the one-paragraph summary, and links to the guide. Don’t paste the guide into the entry: two copies of migration instructions diverge the first time someone fixes a step in only one of them. One canonical guide, referenced from every announcement, reminder, and deprecation warning.

Where should the changelog live?

Teams with a docs site eventually ask whether the changelog should be a page inside it. The real answer is a two-layer split, because the two placements solve different problems:

  • The changelog needs its own canonical home — a stable URL with feeds, per-entry permalinks, and pages that work as link targets from chat, docs, and social. It has announcement duty; a section buried in docs navigation can’t do that job.
  • The docs need a loud pointer to it. A top-level “Changelog” item in the docs nav, and — if you want the news visible where readers already are — a what’s-new widget in the docs header. Docs readers are exactly the returners the changelog exists for.

What matters is that one of them is canonical and the other points at it. Two changelogs — one in the docs, one on the marketing site, updated on different schedules — is the same divergence bug as the duplicated migration guide, wearing a different hat.

Anti-patterns

  • Docs that outsource the present to the changelog. A stale page saying “see the changelog for current behavior” inverts both documents’ jobs: it makes learners do archaeology because writers skipped an edit. If the changelog knows something the docs don’t, the docs are wrong right now.
  • Silent docs edits for behavior changes. The docs diff is not an announcement channel — no returner re-reads reference pages looking for what moved. Edit-in-place without an entry is how users find out about changes from their own error logs.
  • The migration guide pasted into the entry. Divergence bait, as above. Announce in the changelog; maintain the steps in one place, in the docs.
  • “Last updated” as a fake changelog. A timestamp with no diff tells returners exactly enough to worry. Either the change deserved an entry or the edit deserved silence — the timestamp alone is neither.
  • The changelog buried in docs nav. Three levels deep under “Resources” is where announcement duty goes to die. Top-level link, own URL, feeds.
  • Versioned docs for a hosted product. Maintenance debt cosplaying as rigor. One live version → one live docs set, with the changelog carrying history.

Where Wakelog fits

Wakelog is built to be the changelog half of this split: a hosted, canonical changelog page with stable per-entry permalinks your docs can cite in “Changed in” notes, RSS and JSON feeds for returners who subscribe, tags to separate breaking changes from routine ships, and an embeddable what’s-new widget you can drop into your docs site’s header. Entries post from the same pipeline that ships your release — web, curl, or CLI — so the ship-together rule is one extra line, not a separate chore. Honest caveat: Wakelog does not host documentation — it pairs with whatever your docs run on, and your changelog stays exportable as a portable changelog.md if you ever restructure.

Give your changelog a canonical home   Next: changelog page design →

Related guides

Last updated 2026-07-28 · All guides