Saltar al contenido principal

When to version, when to skip

Pro

Doc versioning lets you maintain multiple versions of your docs simultaneously — v2.0 and v3.0 live side-by-side, each readable at its own URL. It's powerful and most teams don't need it.

The case for versioning

You should version your docs if all three are true:

  1. Your product has versioned releases that ship months apart. API v1 vs v2. SDK 4.x vs 5.x. SaaS major release with breaking changes.
  2. Customers stay on older versions for real reasons. Locked-in deployment, incompatible integrations, contractual freeze.
  3. The breaking changes are documented as such. Customers actually need different docs for different versions.

If any of those isn't true, versioning is overhead.

The case against

Versioning is the most-asked-for feature in docs that turns out to be the most-regretted feature.

  • Each version is a fork of the docs. Changes don't auto-propagate. A typo fix on v3 doesn't fix v2.
  • Stale versions accumulate. Six months in, you have v1.0, v1.1, v1.2, v2.0, v2.1, none current except v2.1. The drift becomes invisible.
  • Visitors land on stale versions. Old URLs get linked from old blog posts and StackOverflow answers. New visitors get pointed at outdated docs.

If your product changes incrementally (most SaaS), prefer "current docs always reflect current product" plus a separate dated changelog page for the history.

When to skip — what to do instead

  • Mark deprecated features inline. Add a :::warning Deprecated::: admonition with a link to the replacement.
  • Use a changelog page. A simple date-ordered list of what changed. Searchable, scannable, doesn't require a versioned site.
  • Use git history via GitHub Sync. "What did the docs say six months ago" is a git log away.

When to version — what to do well

If you have decided versioning is right:

  • Pick a versioning convention and stick to it. Semver (v2.3.1), date (2026-04), or release name (amber, bronze). Mixing is confusing.
  • Don't version more than 2–3 active versions. Each one is a maintenance commitment. Cap the count by deprecating the oldest when a new one ships.
  • Make the latest version the default. Default URL → latest. Old versions live at /docs/v1.x/.... Visitors landing on root always get current.
  • Add a banner to old versions. "You're reading v1.x. The latest version is v2.x — link it directly." Not subtle — make it impossible to miss.
  • Sunset stale versions explicitly. Six months after a major release, archive the previous one. Keep a static archive page if you want; remove from the live nav.

Setting it up in Docsio

Project settings → Versions → Tag version. The current state of the editor becomes the named version. From then on:

  • Editors keep working on the live (default) version.
  • The tagged version is read-only; visitors can navigate to it via the version dropdown.
  • Bulk-edit operations don't propagate — edits to the live version stay on the live version.

Roll back to a tagged version any time via the same Versions tab — see Rolling back.

What we don't recommend

  • Versioning every minor release. Version 1.5.3 and 1.5.4 don't need separate docs.
  • Versioning before your product has versioned releases. Don't pre-build complexity.
  • Letting old versions outnumber active ones. When the version dropdown has eight entries and only two are still relevant, you've lost the plot.