Your Docs Describe the Latest Release, and Your Biggest Customers Are Two Versions Behind

A customer's platform team schedules a maintenance window to rotate certificates on your product. They're running a self-hosted release from last year because their change-control process only allows two upgrades a year. They follow the procedure on your docs site, step by step. Step four uses a flag that was added in a release they don't have. The command fails halfway through, the service won't start, and your support team gets an urgent ticket on a Saturday night.

Nothing in your documentation was wrong. It was accurate for the current release. It just wasn't accurate for the release that customer was actually running, and nothing on the page told them the difference.

This is one of the most expensive documentation problems I see, and one of the least visible, because it never shows up as "the docs are bad." It shows up as escalations from your largest accounts, failed upgrades, and support engineers who keep a private list of which instructions changed when.

Why "latest only" works until it doesn't

Most documentation sites describe exactly one version of the product: whatever shipped most recently. For a SaaS product where every customer is always on the current release, that's fine. It stops being fine the moment any of these are true:

• You ship self-hosted, on-premises, or appliance builds. Customers upgrade on their schedule, not yours.
• You sell to regulated or enterprise buyers. Their change-control processes mean they deliberately run older releases.
• You maintain long-term support branches. You've promised to support a release for years, but your docs stopped describing it the day the next one shipped.
• You ship hardware or firmware. Devices in the field run whatever they were flashed with, and plenty never get updated.
• You publish SDKs or client libraries. Developers pin a version and stay there until something forces them to move.

In every one of these cases, the customers most likely to be on an older version are often your largest and most cautious accounts. They're also the ones least likely to tolerate a procedure that breaks their environment.

The failure modes are predictable

When docs describe only the latest release, the damage tends to fall into a few patterns:

• Missing features. The docs reference a setting, flag, or endpoint the customer's version doesn't have.
• Changed behavior. A default changed, and the customer reads about the new default while running the old one.
• Removed instructions. The procedure the customer needs was deleted when the feature it described was redesigned, so it's gone from the site entirely.
• Upgrade instructions with no starting point. The upgrade guide assumes you're coming from the previous release, not from three releases back.

That last one connects to a problem I've written about before: customers who stay on v1 because nobody wrote the migration guide. Old-version customers who can't find accurate docs for where they are have even less chance of finding a safe path to where you want them to be.

Decide which versions you actually support

Before touching any tooling, answer a business question: which releases do you support, and for how long? Versioned documentation is only as clear as your support policy. If your sales team, support team, and engineering team each give a different answer, your docs will too.

Write the policy down in one place customers can see. It should state which releases are supported, when each one reaches end of support, and what "supported" means (security fixes only, or bug fixes too). Then let the docs follow the policy. Every supported release gets accurate documentation. Unsupported releases get archived, clearly labeled, and left alone.

This also keeps the work bounded. You don't need docs for every patch release ever shipped. The Docusaurus documentation, for example, recommends keeping the number of versions under ten and avoiding new doc versions for patch releases that don't add features, because they only create duplicated files nobody reads. That's sound advice whatever tool you use.

Choose a versioning model that matches how you ship

There are two common approaches, and the right one depends on how much the product changes between releases.

Separate doc sets per supported release. Each supported version gets its own copy of the docs, with a version selector on the site. Most docs-as-code tools support this. In Docusaurus, for example, cutting a version is one command, which copies the current docs into a frozen version folder:

npm run docusaurus docs:version 1.1.0

This works well when releases differ substantially, or when you need a frozen record of exactly what a release shipped with. The cost is that you must apply a fix to a shared page to every supported version that needs it.

One doc set with inline version notes. A single page describes the current release and marks the differences: "Added in 4.2," "Changed in 5.0," "Removed in 5.0; see the 4.x procedure." This works well when releases change incrementally, and most pages are identical across versions. The cost is discipline: every change has to be annotated, and the notes pile up over time.

Many teams end up with a hybrid: one doc set with inline notes for minor releases, and a separate frozen set for each major release still under support.

Make the version impossible to miss

Whichever model you pick, the reader has to know which version they're reading about, without hunting for it:

• Show the version on every page, not just in a dropdown at the top of the site.
• Tell readers how to find their own version. The exact command, menu, or API call that reports it, linked from every version selector.
• Mark version-specific steps inline, right where they occur. A note at the top of a long procedure is easy to scroll past at the moment it matters.
• Warn readers on unsupported versions. A clear banner beats a quiet 404 or, worse, a page that looks current and isn't.
• Keep search scoped. Search results that mix versions send readers to the wrong page with complete confidence.

Put versioning into the release process

Versioned docs fail the same way unversioned ones do: someone forgets. The fix is to make documentation part of shipping, not something that happens afterward.

If your docs live in the same repository as the code, or at least go through the same review, then a pull request that changes behavior can require a doc change in the same branch, with a version note. When a release is cut, the docs version is cut with it. When a fix is backported to a supported branch, the docs fix goes with it. This is exactly the kind of process an engineer understands instinctively and a documentation team often has to fight for, so it helps to have someone who can make the case in engineering terms.

Where to start this week

You can get a clear picture of the problem in an afternoon:

1. Find out what your customers are running. Ask support or customer success for the version distribution across accounts, weighted by revenue if possible.
2. Pull the version-related tickets. Search support for phrases like "doesn't exist in my version," "flag not recognized," and "upgrade failed."
3. Pick your three most-used procedures (install, upgrade, and the most common configuration task) and walk through each one against the oldest supported release. Note every step that fails or differs.
4. Write down your support policy, even if it's a draft. If nobody can agree on it, that's your first finding.

That exercise usually makes the business case on its own.

Need help with yours?

Sorting out which instructions apply to which release takes someone who can read the code, run the old builds, and write procedures a cautious enterprise customer will trust. That's the work I do. If your biggest accounts keep tripping over docs written for a release they don't have, get in touch. I'm happy to look at your setup and tell you where I'd start.