Documentation Versioning Policy Template
Two documents and three sheets that check every page against its own content one version back, so only pages that actually changed get forked.
Free download · No account needed
Versioning Policy
[Product], [n] documentation pages
The split, in four counts
| Pages checked against their own content one version back | — |
| Pages with zero real divergence, kept as one shared instance | — |
| Pages that diverged at least once, now forked | — |
| Content-instances actually needed, against a full fork of every page | — |
The question a release-wide fork never asks
Not whether the release shipped changes somewhere. Whether this specific page's content differs from what it said one supported version back.
Retained regardless
Every page, forked or shared, snapshotted at each version's release date and retrievable by exact date even if it never appears in the divergence log.
Docusaurus's own versioning guide states the mechanism nearly every static-site doc tool copies: cutting a version copies the entire docs folder into a new versioned directory. The guide's own advice on when to do that is a single yes-or-no per release, checked against whether the release shipped features at all. A patch release gets no separate version because, in the guide's words, cutting one "will only just create unnecessary duplicated files." The decision is binary and release-wide. Nothing in that model asks whether any specific page actually changed.
This pack asks the smaller question instead, once per page. The worked example is Correlate IAM, an invented identity platform with 96 documentation pages across 5 supported versions. Checking each page against its own content one version back found that 62 of 96, 64.6 percent, never diverged across any of the four transitions. The other 34 diverged at least once. Counting the content-states those 34 pages actually need, 154, against forking all 96 pages for all 5 versions, 480, is a 67.9 percent cut in what needs maintaining separately.
Regulated and enterprise customers raise a second question: not which pages diverged, but what a page said on a past date, which Write the Docs' own principles name as a real requirement without a mechanism for it. A page with zero divergences still gets copyedited, and a snapshot dated to each version's release serves the exact wording an audit window asks for, regardless of the fork count above. Whether a release's changes were tracked before reaching a page is the release notes pack; whether a current page matches the product is the documentation audit.
What's in the pack
Content Divergence Log
One row per page per version transition, real divergence only, with a plain sentence on what changed whenever it did.
Version to Docs Map
Every page mapped to how many content-states it actually needs, and at which version each fork point falls.
Support Window Register
Which versions stay active, their release and end-of-support dates, and any agreement that extends retrieval past the standard window.
Versioning Policy
The shared-by-default rule, what retires a fork once its version leaves the window, and the retention commitment stated in one place.
Deprecation Notice Format
One exact shape for telling a reader a page's content moved, with the applies-to range and the support status stated plainly.
A space rule every prompt reads first
Fork a page because the log shows it changed, never because the release did, so a release-wide fork never happens by default.
Snapshot retention built in
Every content-state, shared or forked, dated at its version's release so a past wording stays retrievable independent of the log.
How to use it
- 1
Open it in River, or download it
Open the pack and the agent builds the Divergence Log from your own doc set, or download the blank documents and sheets.
- 2
Send your supported versions and current docs
The version list with release dates, plus the documentation as it stands today, or a recent fork if you already keep one.
- 3
Check each page one transition at a time
Every page compared against its own content in the immediately previous supported version, never the oldest against the newest directly.
- 4
Fork only what the log flags
The Versioning Policy and Version to Docs Map get built from confirmed divergences, so most pages stay one shared instance.
Frequently asked questions
Is this template free?
Yes. Download the whole pack as Word documents and CSV sheets, no signup and no credit card. Edit with AI is a separate, optional path for anyone who wants the agent to check your own doc set against its version history. Nothing happens until you send it your versions.
We already fork our docs for every release. What does this change?
It tells you which of those forks were ever necessary. Run the Divergence Log against your last two or three forks. Any page identical across all of them can retire back into one shared instance, cutting the set you maintain without touching a page that genuinely needs its own fork.
How do you tell a real divergence from a copyedit?
A real divergence changes what the page tells a reader to do: a behavior, a parameter, a default, a constraint. A copyedit changes wording without changing meaning. Checking this on every pull request, rather than in a batch later, is the same review a docs-as-code workflow already runs.
What happens when a version we forked pages for goes out of support?
Check whether any version still in the support window needs that fork's content. If none do, it retires back into the shared instance the page already points to elsewhere. The Versioning Policy states who reviews this and on what schedule, quarterly rather than per release.
Do we still need to keep every old version's docs forever?
Not live and navigable, no. What regulated or contractual retention actually needs is a byte-exact snapshot retrievable by version and date, which every content-state gets regardless of whether it was ever forked. That is a different, cheaper commitment than keeping every old fork on the live version switcher indefinitely.
Does this decide whether a change counts as breaking?
No, and the two answer different questions. Whether a change is reader-facing and which pages it touches is what the release notes pack tracks per release. This pack picks up after that, deciding whether the change was big enough to need its own page instance across the version window.
What format are the downloaded files?
Two Word documents and three CSV sheets, zipped. The documents open in Word, Pages and Google Docs; the sheets open in Excel, Numbers and Sheets. Add a PDF query string to the download if you want to circulate the policy rather than fill it in yourself.
Find out which pages actually need forking
Download the blank Versioning Policy, Content Divergence Log and Version to Docs Map as Word and CSV, or have River check your own doc set against its version history.
Edit with AI