Versioned Docs & Executable Examples

Versioned Documentation and Executable Examples

Two problems undermine trust in technical documentation more than any other. The first is version mismatch: a reader on version 2 follows instructions written for version 3 — or lands from a search engine on docs for a release retired years ago — and nothing works. The second is broken examples: code samples that never ran, or ran once and silently broke when an API changed, so the first thing a new user copies fails.

Both have engineering solutions. Versioned documentation publishes docs for each supported release, makes the version obvious, and steers readers toward current guidance. Executable examples treat every code sample as a test that runs in CI against the dependency versions the docs claim to support. Together they turn documentation from something that decays into something that is verified on every change.

TL;DR

Document only supported versions, aligned with your release and support policy; mark everything else clearly as unsupported.
Provide a version switcher, a banner on old or pre-release versions, and canonical URLs pointing search engines to the current docs.
Keep docs in the same repository as code and update them in the same pull request.
Make examples executable: doctest, Rust doc tests, Go example functions, notebook runners, or snippets included from tested files.
Run examples in CI against declared dependency versions, including the minimum supported ones.
Check links, build docs with warnings as errors, and review docs changes like code.

Quick Example

A Python function whose docstring example is also a test:

A CI job that runs docstring examples and the documentation's code samples against the oldest and newest supported dependency versions:

If an API change breaks an example, the pull request fails — and the person changing the API fixes the docs in the same change.

Core Concepts

Deciding What to Version

Documentation versions should follow the support policy of the software:

Versioning every patch release multiplies maintenance for little benefit; most projects version by major or minor release and note patch-level differences inline. Retire docs for unsupported versions — or keep them archived with a prominent warning and excluded from search indexing.

Reader Experience Across Versions

Version switcher in the navigation, preserving the current page when switching where it exists.
"Latest" and "stable" aliases, so links and bookmarks reach current docs.
Banners on old versions ("You are viewing docs for 2.x, which is no longer supported") and on pre-release docs.
Canonical URLs (<link rel="canonical">) from versioned pages to the current version, so search engines rank current docs first.
"Added in" and "changed in" notes for features within a version line.
Migration guides between major versions, linked from release notes. See Release Notes and Changelogs.

Tooling for Versioned Sites

Snapshot-based versioning (copying docs per release) makes old versions easy to fix but duplicates content; branch-based versioning builds each version from its release branch, so fixes must be backported like code. Choose based on how often old versions need updates.

Docs in the Same Change

The most effective process rule: a pull request that changes behavior updates the docs. Keeping docs in the same repository as code (see Docs as Code), adding a docs checkbox to pull request templates, and having reviewers check docs as part of review keep versioned docs aligned with the code each release is built from.

Executable Examples

Approaches by Ecosystem

Snippet Inclusion

For longer examples, the most robust pattern is to keep the example as a real, tested file in the repository and include marked regions of it into the docs at build time. The example is compiled, linted, and tested like any code; the docs cannot drift because they are generated from it. Most documentation tools support including file regions, either built in or through a plugin.

Testing Against Declared Versions

Docs often promise compatibility — "requires Python 3.10+", "works with React 18 and 19". Make those claims executable: run examples in a CI matrix covering the minimum and latest supported versions of the runtime and key dependencies, and update the docs' stated requirements whenever the matrix changes. Pin documentation build dependencies so builds are reproducible.

What Not to Execute

Some examples depend on credentials, external services, or destructive operations. Run them against local emulators or mock servers where possible, mark the rest explicitly as not executed, and review them more carefully. Never put real secrets in examples; see Secrets Management.

Quality Gates for Docs

Build docs with warnings as errors (broken references, missing pages, invalid syntax).
Check links — internal on every build, external on a schedule, since external sites fail intermittently.
Lint prose for style guide rules (see Documentation Style Guides).
Preview builds for every pull request so reviewers see rendered changes.
Ownership and review dates for pages, so stale content is noticed (see Documentation Review and Maintenance).

Best Practices

Tie Docs Versions to the Support Policy

Publish the support policy, document exactly those versions, and retire or clearly mark everything else.

Make Current Docs the Default

Default links, search results, and the docs home page should all point to the latest stable version.

Test Every Example That Can Run

Treat a broken example as a failing test, and fix it in the same pull request that caused it.

Keep Examples Small and Complete

Short, self-contained examples with imports and setup included are easier to test and easier for readers to copy.

Common Mistakes

Search Results Pointing to Old Versions

Examples That Never Ran

Docs Updated After the Release

FAQ

How many documentation versions should we maintain?

Usually one per supported major or minor release, matching your support policy. Avoid versioning every patch release, and archive or remove documentation for unsupported versions.

What is an executable example?

A code sample in documentation that is automatically run or compiled as part of testing, so the build fails when the example stops working.

How do I test code examples in Markdown documentation?

Use tools that extract and run fenced code blocks — such as doctest with text files for Python — or include examples from tested source files at build time instead of writing them inline.

How do I stop search engines from sending readers to old docs?

Use canonical URLs from versioned pages to the current version, add warning banners to old versions, exclude unsupported versions from indexing, and provide "latest" aliases for links.

Should SaaS products version their documentation?

Usually not. Hosted products typically have a single current version of docs, with changelogs and migration notes for changes; versioned API references are the main exception.