Version your documentation only when readers are genuinely running different versions at the same time and the behaviour differs between them. If that is true, the safe default is a version selector over a small number of maintained versions (current, previous, and anything under a support contract), with everything older archived, marked, and excluded from search. Versioning every release, or versioning documentation for a product everybody runs on the latest release, costs you far more than it returns.
The cost is not the copies. It is that every question now has several answers, and the reader has no reliable way to tell which one applies to them.
Do you need versioned documentation at all?
Three questions decide it. If all three are yes, version. If any is no, do not.
- Can a reader be running an old version right now? A self-hosted product, an SDK pinned in a lockfile, an on-premise install: yes. A pure SaaS with a single deployed version: no, whatever your API version numbers say.
- Does behaviour actually differ? If the difference is three paragraphs across two hundred pages, an inline note handles it better than a second copy of the site.
- Will you maintain both? An unmaintained old version is worse than no old version, because it is authoritative-looking and wrong.
Before you version the whole site, try version badges on the individual statements that changed: “Added in 3.2”, “Removed in 4.0”. Most products need this and nothing more, and it keeps every reader on one page that search engines can rank.
Three models, and what each costs
| Model | How it works | Costs |
|---|---|---|
| Inline version notes | One copy of every page. Differences called out with badges or callouts. | Gets unreadable past two or three concurrent versions. Cannot express a page that was restructured. |
| Version selector over full copies | A separate tree per version, with a dropdown that keeps the reader on the same page across the switch. | Duplicated content, split analytics, and a genuine SEO problem you have to manage deliberately. |
| Latest-only, with a frozen archive | Documentation covers the current release. Old versions are snapshotted, marked, and taken out of search. | Nothing for readers on old versions except the archive. Fine when upgrades are cheap; unacceptable when they are not. |
Most teams that think they need the second model actually need the third with a good archive. The second is right when you support old versions contractually (enterprise, on-premise, regulated) and wrong almost everywhere else.
Lay the versions out so the URL says which one it is
Whatever the model, put the version in the path rather than in a query string or a cookie. A URL that carries its version can be linked in a support ticket, bookmarked, and correctly cached; one that does not will eventually show somebody the wrong page and there will be no way to reproduce it.
docs/
├── v3/ current — indexed, no banner
│ ├── install.md
│ └── upgrade.md
├── v2/ supported — banner: "not the latest version"
│ └── install.md
└── v1/ archived — noindex, banner: "end of life"
└── install.mdKeep the page slugs identical across versions. That is what makes “stay on this page when I switch version” possible: the selector rewrites one path segment and nothing else. When a page genuinely does not exist in the target version, fall back to that version’s index with a message, never to a 404.
Setting it up
-
Decide which versions are live. Write the policy down: current plus one previous, or whatever your support commitment actually is. Every version outside that policy is archived on the day the policy says so, not when somebody remembers.
-
Freeze the archive. An archived version gets no further edits, not even typo fixes. The moment you edit one, you own it again.
-
Put a banner on every non-current page. “You are reading the documentation for v2. The current version is v3.” with a link to the same page in the current version. This is the single most valuable element on the page, and it belongs above the content, not in the sidebar.
-
Set the canonical link. Every archived page should carry a
rel="canonical"pointing at its current-version equivalent, so search engines consolidate the ranking rather than splitting it. -
Exclude archived versions from your own search. A reader searching your site is almost never looking for the old version, and if they are, they will use the selector.
-
Redirect the bare path.
/docs/install/should land on the current version, not 404. Keep that redirect for the life of the site.
The SEO problem, stated plainly
Full-copy versioning creates near-duplicate pages at scale. Search engines will pick one of them to rank, and left to themselves they will often pick the oldest: it has the most inbound links and the longest history. Readers then arrive from Google on documentation for a version they are not running, follow it, and it does not work.
Canonical links from every archived page to its current equivalent. A noindex on versions past end of life. And a version banner that is visible before the reader has read a single sentence of the body, because some proportion of them will arrive on the wrong page whatever you do.
The banner is the one that actually saves people. Canonicals are advice to a crawler; the banner is the only thing that reaches a human who has already landed.
What to do when a version reaches end of life
- Do not delete it. Dead documentation URLs strand support tickets, forum answers and bookmarks going back years.
- Change the banner from “not the latest” to “end of life”, and say what that means: no further updates, no support, upgrade path linked.
- Add
noindex, keeping the canonical in place. - Remove it from the version selector, but leave the URLs reachable.
- Write the upgrade guide before you need it. The moment a version goes end of life, the most valuable page you own is the one explaining how to leave it.
Common questions
Should the version selector stay on the same page or go to the index?
Same page, every time, falling back to the index only when the page does not exist in the target version. Sending a reader to the index is effectively telling them to find their place again, and they will simply switch back.
Do we version the tutorials as well as the reference?
Version the reference, because it describes exact behaviour. Tutorials are often better left unversioned and written against the current release, with a note at the top: they change more slowly than the API surface and duplicating them multiplies your maintenance for very little reader benefit.
How many versions is too many?
Three live versions is comfortable. Five is painful. Past that, the selector becomes a list nobody reads and the maintenance burden starts producing stale pages in the versions you claim to support, which is worse than not offering them.
What about versioning by date instead of by release?
It works for APIs that version by date (2026-08-01) and confuses everybody else. Match your documentation versions to whatever string your users actually type when they pin a dependency.
Doku handles the mechanics with a doc_version taxonomy and a header version switcher that keeps the reader in place, sorts versions naturally so v10 outranks v9, and gives each version its own index. See Features for the setup, and Release Notes and Changelogs for the document that tells readers why to move.