Fourteen versions, one question: discovery for versioned documentation

Dortmund SEO editorial teamupdated 31 August 2026

Your documentation has one page explaining how authentication works. It also has fourteen, because every release since version 2.0 kept its own complete copy of the tree. All fourteen are live, all fourteen are being catalogued, and when somebody searches for that topic, the one that surfaces is from a release nobody has run for two years.

Versioned documentation is correct engineering practice and a serious discovery problem, and almost nobody treats the second half of that sentence seriously. Customers running an older release genuinely need the older text, so keeping it is not optional. What is optional — and almost always left unconfigured — is whether every one of those copies competes for the same questions as the current one.

Fourteen answers to one question

Nobody discovers this through falling numbers. It shows up as a complaint: a customer mentions that searching for a topic returns an outdated page, and support confirms it. Everyone assumes it is an isolated case. It is not — it is the default behaviour of a documentation tool that was configured for correctness and never for findability.

Row three is the quietest and the most voluminous. A release-notes system running for four years produces several hundred pages, each a few sentences long, each structurally identical to the others. Individually harmless; collectively they can outnumber the substantive documentation, and they consume exactly the same capacity when submitted.

How a page is reached at all

The version selector deserves the same warning as a search form: it is an instruction to a human, not a path. If the only way to reach version 3.2 of a page is by choosing it from a dropdown, nothing walks there. Whether that matters depends entirely on whether you wanted those pages found — which is a decision, and one that is almost never taken deliberately.

Route one is not something to give up on in favour of route two. Structural work keeps paying out; a handover pays out once. Where guides link to the reference pages they use and every reference page links back, the whole set stays easier to traverse from then on. The sensible arrangement is to repair the structure until route one carries the load, and keep route two in reserve for what structure cannot solve — a first publication, a version policy change, a migration touching thousands of addresses at once.

The submission limits, plainly stated

None of these ceilings obstructs anything by itself. They become obstructions where a plan was made without reading them, which is the normal state of affairs. Dividing page count by version count by daily allowance takes ten minutes and removes the commonest reason a documentation rollout appears to stall for no visible cause.

It is also worth being clear about what these ceilings are not. They are not a quality signal, and staying below them earns nothing at all. They are a scheduling constraint of the same kind as a build queue or a release window, and they deserve identical treatment: know the throughput, order the work by importance, and do not enqueue anything that does not need to run.

Which copies deserve to be found

The resolution is not to delete old versions. It is to separate two questions that get conflated: which pages should remain reachable for customers, and which should compete for discovery. Those have different answers, and treating them as one is what produces fourteen competing copies.

Recording that policy somewhere visible to the whole team — rather than encoding it only in a build configuration — stops the next engineer from quietly re-enabling a category because it looked like an omission. A shared view in the same environment that holds the coverage data serves that purpose, since the decision and its consequences then sit next to each other.

Applied to a typical documentation set this reduces eight thousand four hundred addresses to roughly six hundred worth exposing — which changes the submission arithmetic from eight days to under one, and changes the competitive situation from fourteen copies fighting each other to one clear answer per topic.

Documentation teams sometimes resist this, and the objection is reasonable: every archived page is real, accurate for its release, and someone might need it. The counter-argument is measurable rather than aesthetic. Fourteen near-identical pages compete and none of them wins; one current page carrying a clear version note wins and answers the question completely. Nothing is hidden — the archived version is still there, still reachable, still correct for whoever needs it.

API documentation and what it produces

Reference documentation generated from source produces one page per endpoint, per parameter set, sometimes per version. It is genuinely useful to developers who already know what they are looking for, and it is structurally poor at being found — because generated pages typically contain a signature, a parameter table and nothing a person would search for in words.

• Expose the endpoint pages, not the parameter permutations. One page per endpoint is a real unit of information. A page per combination of optional parameters is not.
• Add a sentence of prose to each endpoint. What it is for, in the words a person would use. Generated pages without this are effectively invisible for anything except the exact method name.
• Link guides and references to each other. A guide explaining a workflow should link to the endpoints it uses, and each endpoint should link back. This is obvious and almost universally absent.
• Keep the reference on the same domain as the guides. Where it is split off, neither half supports the other, and the split is rarely justified by anything except how the build works.

The second point is where most of the return sits and it is uncomfortable for engineering teams, because a generated page with hand-written prose in it is no longer purely generated. The usual resolution is a description field in the source that the generator carries through — which keeps the text next to the code and produces exactly the sentence that makes the page findable. Tracking which endpoints have that field filled in inside one workspace keeps a job of that size from stalling at forty per cent.

There is a further reason to keep guides and reference material on one domain, which has nothing to do with build convenience. During an evaluation, a technical reader moves between the two constantly — reading a guide, checking an endpoint, returning to the guide. Where the two live apart and do not link to each other, that reader has to search again at every transition, and some proportion of them will not bother. The cost of the split therefore lands on exactly the visitors a software company most wants to keep.

Redirects that eat the allowance

Two documentation restructurings leave behind redirect chains nobody deliberately created. The first pointed the old path at a new one; the second gave that new path a new destination of its own. What remains are addresses passing through two or three stops before arriving, each stop costing work and contributing nothing.

Version migrations make this worse than usual, because a rename in the current version propagates through every archived copy that referenced it. Collapse every chain to a single hop before filing anything, and build the check into the release pipeline — an automated test that fails when any address resolves through more than one stop takes an hour to write and stops the problem from ever accumulating again.

How to tell that anything actually changed

Handing over an address is a request and carries no guarantee whatsoever. The only thing that counts as confirmation is seeing that address turn up in the reporting with impressions attached, and getting there takes several weeks. In between sits a blank period during which no conclusion of any kind is available. That blank period is precisely where impatient teams keep resending the same address, spending capacity to achieve nothing.

Something that works in practice: hand it over a single time, wait a full week without touching anything, and only then check whether coverage moved. If two weeks pass and a correctly handed-over address has still not appeared, look at the page rather than at the process. Typically one of three things is true — no internal link points at it, identical wording exists elsewhere on the site, or the visible content is constructed in the browser after the document arrives. Resending fixes none of them. Following the whole sequence within a connected environment makes it clear which of the three applies, and does so without anyone maintaining a parallel spreadsheet.

Doing the steps in a workable order

Getting the order right counts for more here than in most projects, since every stage renders the measurements taken before it meaningless. Hand pages over before the version policy exists and the handover is thrown away; read the reports before establishing that pages are delivered at all and the reading rests on an incomplete record.

Step one falls to a technical review and admits no postponement, since everything after it rests on the outcome. Which topics are being searched for at all — and therefore which sections go first in step five — comes from keyword research rather than from an assumption about which parts of the product matter. Where the same text sits at several addresses, the remedy is on-page work and not further filing. Running the three from a single account keeps the order intact, because each step's result is on screen when the next begins.

Check which version of your docs is actually surfacing

Questions from engineering and documentation teams