Versioned docs: keep language and API release separate
Documentation routing needs two coordinates: software release and language. A fluent page for the wrong release can send a reader to parameters or operations that do not apply.
Resolve the requested release first. If its documentation is unavailable in the preferred language, state that gap without substituting another technical contract.
A language switch must not become an undocumented API upgrade
Imagine a documentation site with an English guide for release 2 and a French guide for release 1. A language switch sends a French reader to the newest English page whenever the release-1 translation is missing. The destination is readable and the link works, but two dimensions changed at once: language and software version.
This fictional example illustrates why a single “latest translation” link is insufficient. A reader trying to understand the installed release may follow instructions that belong to a different contract.
| Requested documentation | Available material | Editorial decision to make explicit |
|---|---|---|
| Release 1, French | Release 1, French | Link to the equivalent guide |
| Release 2, French | Release 2, English only | Announce the language fallback |
| Release 1, English | Release 2, English only | Explain the version gap or archive policy |
| Retired release | Historical guide and migration note | Distinguish reference material from current guidance |
The matrix is a proposed documentation design. It does not assert that a particular site has all of these releases or translations.
Give each link enough context to survive extraction
A link labelled “Read more” relies heavily on the surrounding interface. A link labelled with the guide topic, release and language carries more of its meaning into an extracted document. Use that information where a reader could otherwise choose the wrong reference.
The llms.txt proposal supplies a way to organise selected resources. The editorial task is to choose accurate destinations and descriptions. Adding the file does not correct a redirect that silently changes the API release.
Google's guidance on localised versions concerns language and regional alternatives. Do not declare unrelated release documents equivalent merely because they discuss the same product. A language annotation should reflect the relationship that actually exists.
Test the final destination, including redirects
For a representative cell in the matrix, open the exact link and record the final page title, release and language. Check an available translation, a missing translation and an archived release. These cases exercise different decisions.
A redirect may be a deliberate editorial choice. What matters is whether the reader can understand the change and whether the destination still answers the original need. If the old behaviour cannot be documented on the new page, preserve a clear historical reference or explain its absence.
When a translation is published later, update both the link and any fallback notice. Otherwise a page can correctly route to French while still warning that only English is available. The surrounding text is part of the routing experience, not a separate cosmetic layer.
Finally, keep the version matrix with the release process. A filename convention can help automate checks, but it cannot decide whether two pages are true equivalents. That relationship depends on the content and the supported behaviour.
Do not manufacture translation relationships
Google's localized-version guidance concerns genuine language or regional alternatives. An independently written article about a different problem should not be attached as a translation simply because its language matches an empty slot.
Keep the same distinction in your documentation index. Two pages can be related without being equivalent. Label a migration explanation as related reading, not as the translated API contract.
This matters during partial localization. Publishing a useful original English article does not require pretending that an unrelated French article is its counterpart.
Test questions that expose the routing
A general request such as “explain this API” is too forgiving. Test a question about a parameter that changed, a retired operation or a language whose translation is incomplete.
The expected result should identify the correct source, the release and any limitation. If the system cannot resolve the requested version, an explicit gap is preferable to an answer stitched together from incompatible documents.
Record the retrieved URL as well as the final response. A correct-looking answer with the wrong source is still a routing defect.
Update routing when a release changes
Assign responsibility for the matrix when documentation changes. Removing a release, renaming a directory or publishing a translation can break a previously valid relationship without altering llms.txt syntax.
Before announcing a documentation update, review the cells that changed and verify their final destinations. Preserve archives only when you can explain their status, and link migration guidance from the relevant old material.
For each empty or retired cell, state the intended destination or the absence of an equivalent. This makes a missing translation visible before a redirect silently substitutes a different release.
Keep release-specific warnings beside the affected links. The llms.txt best practices help organise the index, but readers also need enough context on each destination to identify its scope.
