What a documentation migration must preserve

How we researched this

Research synthesis, checked October 29, 2026. We reviewed primary research from Pew Research Center and PLOS ONE, the HTTP standard, MDN, Google Search documentation and Read the Docs documentation. Research-model outputs helped find sources; the original sources were inspected separately. Older studies provide measurement lessons, not current failure rates for documentation platforms. The preservation contract, example and release matrix below are our proposed method. We did not migrate a sample of sites, measure customer outcomes or benchmark vendors.

What counts as a successful documentation migration?

A migration can look finished to the team moving files and unfinished to the person following an old support link. The new homepage loads. The sidebar has pages. The build is green. But a bookmarked installation section lands at the top of a different guide, an image has disappeared, or an example now targets a different API version.

These are distinct failures. Treating them as a single broken-link problem makes them harder to find.

We recommend defining success around three questions:

1. Can the reader arrive? The old address reaches the intended destination without a loop, unexpected login or missing asset.
2. Can the reader find the same answer? The destination preserves the relevant task, version, language and section, or clearly explains an intentional change.
3. Can the reader use it? Commands, examples, downloads and navigation still support the task.

Search visibility adds another requirement: pages intended for public search need consistent discovery and indexing signals. Google explicitly says a successful HTTP response does not guarantee indexing. A page with an empty or error-like body can be treated as a soft 404 even when the server reports success. Google HTTP status guidance

For a team replacing a documentation platform, the useful acceptance question is therefore not simply whether the import completed. It is which reader promises the import preserved, and what evidence supports that conclusion. That standard should be agreed before the old site disappears.

What link-decay research actually measures

Pew Research Center reported in May 2024 that 25% of the combined sampled-page set captured between 2013 and 2023 was inaccessible at its later check. Within the respective year cohorts, the figures were 38% for 2013 and 8% for 2023. These are different-aged groups, not annual probabilities that a page will fail. They are not documentation migration failure rates. Pew findings

The methodology describes roughly 1 million pages, about 91,000 per year, sampled from Common Crawl. Although the findings summarize availability as of October 2023, checking rounds ran from October 12 through November 6. Inaccessibility was determined through specified response codes or DNS failure. Ambiguous cases, including soft 404s and some timeouts, counted as accessible. Pew methodology

That definition matters. A status-based study can answer an availability question without answering whether an old instruction, diagram or section is still present. This is a boundary of the measurement, not a reason to dismiss it.

A different approach appears in Shawn M. Jones and colleagues' 2016 PLOS ONE study. Starting with 1,059,742 web references from scholarly articles published in 1997-2012, the researchers sought representative archived content and compared it with live content in August 2015. After archive availability and extraction filters, 241,091 references remained for content-drift analysis. The surviving analysis set was therefore much smaller than the starting collection. Jones et al.

Our inference is narrow: keep an inspectable pre-migration baseline. Without one, a team can prove that something exists at a URL but struggle to prove that the necessary information survived. Neither study supplies a universal percentage to put in a migration risk forecast.

Write a preservation contract before importing

A redirect spreadsheet usually records an old URL and a new URL. Expand it into a small acceptance record that describes the answer the URL is supposed to provide. This is our proposed working document, not a published industry standard.

Inventory inputs should include the existing sitemap, source files, navigation, known inbound links, available access logs and high-value support bookmarks. No one input is guaranteed to be complete. An unpublished draft in a repository is different from a public URL. A public page absent from the sidebar can still be important.

Store a dated source export or rendered snapshot in an access-controlled location. Keep screenshots for layout and images, plus text or source for detailed comparisons. Record the product release the snapshot describes. Do not put private documentation, credentials or customer examples into a public archive to make this easier.

Make retirement explicit. Some pages should disappear because they describe an unsupported product or duplicate a better guide. Record why, who approved it and what a reader should see instead. A deliberate retirement is an editorial decision; an unreviewed omission is a migration defect.

For a small site, one spreadsheet may be enough. For a larger one, generate the records from source metadata and review exceptions. The important property is a shared definition of preserved meaning, not a particular tool.

Why redirects do not fully protect section links

Consider an old link to /docs/install#linux. A server redirects the page to /guides/setup, where the corresponding heading now has the identifier linux-installation.

Under RFC 9110, when a redirect's Location value has no fragment, the user agent must inherit the original fragment. The resulting address can therefore retain #linux. That does not create a matching section in the new document. RFC 9110, section 10.2.2

MDN explains that the fragment is processed by the client after the resource is retrieved. For an ordinary HTML section link, it can identify an element by its id. The fragment is not sent to the server as part of the request. MDN URI fragments

An explicit fragment in the redirect destination changes that inheritance behavior. Client-side routers can also implement their own navigation, so test the actual site rather than assuming ordinary HTML behavior.

This gives us a specific testing requirement: open the complete old link in a browser and verify where it lands. A server-side status checker alone cannot establish that the reader reaches the intended section.

For this hypothetical example, possible repairs include retaining the old heading identifier, adding a compatible anchor beside the renamed section, or implementing a reviewed client-side mapping. A redirect with one explicit fragment can serve a single known destination, but it is not a general mapping for every old section on a long page. Ordinary server requests do not tell you whether the reader arrived with #linux or #windows.

Test at least these variants in the proposed rehearsal:

• An unchanged section identifier on a moved page.
• A renamed heading with an old shared link.
• Two headings that would otherwise produce the same identifier.
• A section inside content that is initially collapsed.
• A heading near the bottom of the page on mobile.

Check that the target is visible and understandable after navigation. Finding an element with the expected identifier is useful evidence, but it is not enough if a sticky header covers it or a closed panel hides its instructions.

Preserve version meaning, not just the nearest page title

An old v1 authentication guide and a new v2 authentication guide may have almost identical titles. Redirecting the former to the latter can still give a reader the wrong credential format, endpoint or request example. Our recommendation is to treat the product version as part of the answer being preserved.

Platform behavior deserves inspection rather than assumptions. Read the Docs documents page redirects that apply across versions, while exact redirects can target a specific full version or language path. It also says redirects normally apply to missing pages unless forced, and do not apply on pull-request previews. A preview check on that platform therefore does not establish production redirect behavior. Read the Docs redirects

This is an example of why an import demonstration is not a migration guarantee. Ask how the destination system handles version routes, language routes, aliases and redirect precedence. Request evidence for the actual configuration you intend to deploy.

For each supported version, review one complete reader task, not just the version selector. Start from an old deep link, confirm the version label, follow the example and navigate to a related page. Check that navigation does not silently jump into the latest version.

If two versions contain genuinely equivalent material, consolidation may be reasonable. If behavior differs, a matching title is not sufficient evidence of equivalence. A useful review record names the differences that matter: parameters, defaults, permissions, supported environments and failure behavior.

Older unsupported instructions may need a visible warning or an upgrade guide. Keeping them available does not require presenting them as current advice. Conversely, moving everything to a latest page should not erase information still needed by supported customers. Decide the support policy first, then make the routes and labels reflect it.

What Google guidance does and does not promise

Google's site-move guidance makes two points that should be read together: permanent redirects do not cause a loss in PageRank, and significant site changes can produce ranking fluctuations during recrawling and reindexing. Neither point guarantees unchanged organic traffic. Google site moves

Google also distinguishes canonical signals. Redirects and canonical annotations are strong signals; sitemap inclusion is weaker. These mechanisms concern duplicate or very similar pages, and Google still selects the canonical. Google canonical guidance

Our application to documentation is to review technical signals alongside the content decision. If two version pages describe different behavior, do not assume they belong in one duplicate-page group merely because they cover the same feature. If a page moves, check the new page's canonical and internal links rather than assuming the redirect updates everything else.

Google warns against redirecting many old pages to an irrelevant destination such as the homepage, which may be treated as a soft 404. It recommends keeping redirects for as long as possible, generally at least a year. That is not an instruction to delete them on day 366. Google site moves

Avoid reducing the release to a promise of no SEO loss. The controllable deliverable is a documented mapping, consistent signals, useful destinations and a monitoring plan. Search outcomes remain observations to measure after release.

A migration that passes a link check but fails a reader

The following is a hypothetical example, not a measured customer incident.

A product has a webhook guide with a signing example, a retry-policy section and an event diagram. During migration, the team merges it into a broader events guide. The old address redirects and the new page returns HTTP 200.

A status-only check passes. A content review finds that the signing example was shortened and no longer explains timestamp validation. A browser check finds that the old #retry-policy link has no matching target. An asset check finds that the diagram still points at a host scheduled for shutdown.

All three defects can coexist with a successful response. They also need different fixes: restore the security-relevant explanation, preserve the section target, and move or deliberately retain the asset hosting.

Now change one assumption. Suppose the old retry section is intentionally obsolete because the product no longer retries events automatically. Copying it exactly would preserve the text but damage accuracy. The correct migration decision may be an updated explanation and an explicit transition note, approved by the product owner.

This is why our proposed contract records both the old content and the intended decision. Text similarity is a useful way to find material for review. It cannot, by itself, decide whether a change is correct.

The acceptance record for this example should say which retry behavior is current, which versions retain the old behavior, where existing links land and how the signing example was checked. That is more useful than a single green migration status.

A practical release matrix for documentation

Use the following as a starting point for a rehearsal on a staging copy you control. These are proposed checks, not results from a vendor comparison.

Automate repeatable checks across the full known inventory where practical: response status, redirect targets, asset requests, headings and metadata. Use browser tests for client behavior and human review for whether an answer is still correct. The layers complement one another.

Prioritize deeper review by consequence. Installation, authentication, billing configuration, destructive commands and widely shared troubleshooting pages deserve attention even when their traffic is modest. A low-traffic page may serve a rare but expensive failure.

Write down what was not checked. If only one language or version was exercised, that is the coverage boundary. If a third-party download cannot be fetched in staging, record it as unresolved rather than counting it as a pass. An honest exception list helps a release owner decide whether to proceed.

For executable examples, use disposable accounts and non-production resources. Preserve realistic preconditions, but replace secrets and customer-specific values. The goal is to test the instructions without creating a second operational problem.

Keep the release reversible and measure the right things

Before switching traffic, save the previous content, route configuration and deployment reference. Agree who can restore them and which failures justify a rollback. Verify that the restoration path is usable before relying on it.

Our proposed rollout sequence is deliberately simple:

1. Freeze a baseline or record subsequent edits so the migration does not overwrite new work.
2. Rehearse the import and mapping in a controlled environment.
3. Resolve blocking content, route and access defects; document accepted exceptions.
4. Release the approved content and configuration together.
5. Recheck public entry points and critical tasks on the live site.
6. Monitor new failures and compare performance with the saved baseline.

Keep operational and search measurements separate. An unavailable guide is a release problem that can be investigated immediately. Search impressions and clicks describe a slower, noisier outcome. A short-term change alone does not identify its cause.

Useful monitoring records include failed old-URL requests, unexpected final destinations, broken assets, search queries with no useful result and support reports tied to a page. Separate newly introduced defects from known retired pages and unrelated external-link failures. Otherwise, an error total can rise without telling the team what to fix.

For organic search, compare the same relevant page groups before and after the move, including both old and new addresses where appropriate. Note simultaneous content changes, product launches and seasonality. Do not attribute every traffic movement to the migration.

Choose an owner for continued redirect and content maintenance. The migration is a release event, but old bookmarks and support links do not stop existing when the project ticket closes.

Questions to ask before choosing a new docs platform

A polished sample site can demonstrate the reading experience. It does not establish what happens to your existing documentation. Ask for a rehearsal using a representative, non-sensitive subset of your own material.

The most useful questions are concrete:

• Can existing public paths stay unchanged, and where are exceptions recorded?
• What happens to heading identifiers and links to individual sections?
• How are supported versions and languages represented after import?
• Do code examples, images, downloads and internal links survive rendering?
• Where are redirects configured, and does the test environment exercise the same rules?
• Can the team export the result and restore the previous release?
• What evidence will show that the migration preserved the answers readers need?

Compare responses against your preservation contract. A platform that requires a different path structure may still be a good choice if the mapping is explicit and tested. A platform that keeps every path may still require substantial content and browser checks.

For related planning, our guides cover documentation versioning and moving Confluence material into public docs. For executable examples, the documentation testing research report separates runnable checks from proof that a guide is understandable.

The release decision should rest on evidence for your actual pages and reader tasks. A successful import, a clean link report and a beautiful homepage are useful milestones. None is a substitute for checking the answers people came to use.

Limitations

This report does not estimate how often documentation migrations fail or rank migration tools. Pew studied broad-web availability, while the PLOS ONE study examined references in older scholarly literature with substantial archive and extraction filtering. Neither sample represents modern documentation migrations. Standards describe expected behavior, not universal implementation quality. Provider guidance was checked on October 29, 2026 and can change. The proposed contract and tests have not been validated as a predictive benchmark. They cannot guarantee search rankings, complete coverage or correct product instructions without appropriate review.