Versioned documentation snapshots

[GuanzhouSong]

What I need from you

Sign-off on a docs snapshot policy. The code is built and reviewable below — nothing here reaches a reader until this table is filled in. My recommendation is in the right column; reply "agree" or edit it.

Question	Options	My recommendation
When do we cut a snapshot?	every DocumentDB release / docs milestone / ad hoc	Every DocumentDB release — it matches the version number a user actually types
How many do we host?	2 / 3 / 5 / all	3. Older ones link out to git tags
Do archived pages appear in Google?	yes / no	No — reasoning below

---

The problem

Today nothing on documentdb.io says which version you are reading. A user on an older release follows an install command that does not exist in their build, it fails, and they have no way to tell whether they made a mistake or read the wrong page.

Our only current answer is "go read the Markdown on a git tag." That is not an answer for anyone not already comfortable browsing a repository.

We are the outlier. Postgres, MongoDB, Redis and Kubernetes all ship browsable versioned docs. We are the project whose install command changes between releases and we are the one without them.

The top half is production right now. The version indicator is the entire difference.

What it looks like for a reader

Finding it. The entry point sits at the bottom of the docs index, below the section cards — someone who wants current docs never steps over it; someone hunting for their version finds it where they land after not finding what they wanted.

Choosing. Current leads and is marked latest release, because most people arriving here are checking they are in the right place, not looking for an archive. Versions we do not host get an honest answer — links to the tags and releases — rather than a dead end.

Knowing where you are. Every archived page says so twice: a badge in the sidebar and a banner above the content with one click back to current. Someone arriving from a search engine lands mid-page with no memory of clicking anything, and this is exactly the confusion the feature exists to remove. Amber, not red — being here is valid, we are just saying where "here" is.

Moving between versions. Each entry goes to the same page in that version, not to that version's home. "How did this work in v0.114-0" is one click, from any page, current or archived.

Why not just keep annotating changes?

Fair challenge — we already annotate ("added in", "default changed in"), and that is cheaper. But annotations tell a reader what changed; they cannot show a reader the page as it was, and they break down completely when pages are restructured.

That is not hypothetical. It is visible in the two sidebars for the same section:

Docker and Linux Packages quick starts did not exist at v0.114-0. The VS Code Extension Guide did, and is gone today. No annotation can recover a page that was deleted.

The two judgment calls

Archived pages are not indexed. The failure this prevents is also the one it could cause: if Google ranks a v0.114-0 install page above the current one, we have hurt the majority to help a minority. Snapshots are for people who already know which version they want; search should keep sending everyone to current docs. The trade-off is real — someone Googling "documentdb v0.114 install" will not find the snapshot. I think this is the right side to err on, but it is your call, which is why it is in the table.

Snapshots are never edited. Current pages get editorial corrections at build time; archived pages deliberately do not. A snapshot we quietly keep fixing is not a snapshot, and its whole value is that it matches what the reader installed. The cost is that known-wrong content stays wrong in the archive — the banner is what makes that acceptable.

Cost, ownership, reversibility

• Cost. 18 pages per snapshot, generated at build time. Three snapshots ≈ 54 extra pages. No new infrastructure, no new service.
• Who maintains them. Nobody. That is the design — a snapshot is generated from a git tag and never touched again.
• Reversibility. Removing the config removes every archived URL. Nothing else on the site depends on it.
• How we will know it worked. In 90 days: version-mismatch questions in Discord and issues, and traffic to /docs/versions/*.

Engineering notes (reviewers)

Preview and the tagging blocker. documentdb/docs has no git tags and no release-notes/ directory, so with the upstream config the version list is empty. The last commit (2106094) points the compiler at a fork carrying a v0.114-0 tag purely so this could be previewed — it is marked REVERT BEFORE MERGE and touches two files.

Base path. Previewing a docs change on a fork used to require hand-editing the deploy workflow. It is now derived: upstream resolves to no base path (deploy behavior byte-identical to today), any fork resolves to its own repo name. That is what made these screenshots reproducible by any reviewer.

Bug found while producing these screenshots. Both the switcher and the versions index derived their "current" label from the newest snapshot label — but a snapshot is by definition an older release, so each rendered the same version twice ("Current (v0.114-0, latest)" directly above "v0.114-0 (archived)"). Fixed in 35eaec3, with a test pinning the constant to the release the rest of the site documents.

Not pictured: mobile. Verified in the built markup rather than screenshotted — the banner renders at every width, and the collapsed nav summary reads "Getting Started navigation (v0.114-0)". The sidebar badge is inside that disclosure, so on mobile the redundancy is banner + summary rather than banner + badge.

Verification. npm run lint clean · npm test 85/85 · production build exports /docs/versions, /docs/versions/v0.114-0 and 18 archived pages · sitemap wrote 274 URLs, excluding all 19 archived pages while keeping the versions index listed.