Versioned Documentation RAG: Keep APIs and Examples Aligned
Build a documentation corpus that identifies release versions, preserves code blocks and rejects retrieval from the wrong API generation.
KAIROXO
Versioned documentation RAG fails when the retrieved passage is correct for the wrong release. A code example from an older API can look authoritative, carry a valid URL and still be incompatible with the application being built. More scraping or a larger text index does not solve that identity problem.
A useful documentation corpus preserves which project, release, language and section each passage describes. This article extends KAIROXO's web-to-Markdown and provenance guides by concentrating on version boundaries. The access layer can obtain permitted pages; interpreting versions, chunking examples and filtering retrieval remain application work.
Establish a version-aware source inventory
Start with the official documentation entry points and a bounded list of projects. Identify whether the URL refers to a fixed release, a maintained branch, a rolling stable alias or an unversioned guide. Do not silently treat “latest” as a permanent version identifier. Record the observed alias and the resolved release separately when the source provides enough evidence.
Keep the page URL, canonical URL, title, language, retrieved time and version evidence. A menu selection alone may not identify the content if navigation state is client-side. Verify a version label or another source-controlled signal in the page itself. Where no version can be established, label it unknown or rolling rather than inventing a semantic version number.
Preserve code and nearby constraints
Extract headings, paragraphs, code blocks and language labels without flattening code into prose. Keep indentation, line breaks and the explanatory paragraph that states prerequisites. An example may require a particular runtime, feature flag or package import; a standalone function copied without that context can be misleading.
Avoid mixing terminal output with commands unless the source clearly labels both. Distinguish placeholder credentials from literal values. Store a digest of the extracted passage and retain the source section anchor. The image beside this section is editorial illustration; the corpus itself must come from source text, not text guessed from a stock photo.
Use metadata as a retrieval boundary
A chunk identifier should incorporate the project, release identity and section, with a content revision or digest for tracking changes. Store schemaVersion for your own corpus format separately from sourceVersion for the documented software. These fields answer different questions and should not share an overloaded “version” column.
Metadata | Question answered |
|---|---|
sourceVersion | Which software release does this passage describe? |
retrievedAt | When was this copy obtained? |
sectionAnchor | Where can a reader verify the passage? |
contentDigest | Did the extracted passage change? |
schemaVersion | Which corpus format interprets the record? |
Filter by the requested project and compatible release before ranking passages. Similarity alone can favor an older example with closer wording. When the requested release is absent, disclose the gap; do not silently substitute a newer API and present it as compatible.
Refresh aliases without erasing history
A rolling stable URL can change while its address stays the same. Compare extracted content and version evidence during refresh, then create a new revision when warranted. Preserve the previous snapshot if it supports existing applications or citations. Deleting old material just because it is no longer current can make historical answers impossible to audit.
Treat redirects to a landing page or missing version as a review signal. A successful request does not establish that an old release still exists at the destination. Use conditional requests and bounded refresh policies where appropriate, but keep version interpretation distinct from HTTP cache freshness. Freshly fetched content can still describe an older release.
Evaluate answers with deliberately conflicting versions
Build a small test set containing questions whose answers changed between two supported releases. Require the retrieval result to use the requested release, preserve the relevant code block and link to the correct section. Also test missing releases, renamed methods and examples with identical titles across versions.
A good result is not just a fluent answer. It should identify the version used, cite its evidence and acknowledge unsupported combinations. If an answer combines an import from one release with a method from another, mark it wrong even when each fragment exists somewhere in the corpus. This catches a failure that ordinary relevance tests can miss.