Documentation Platform Migration Checklist

Use this checklist when moving from one documentation platform, framework, or hosting provider to another. The safest migration creates a complete private replacement, validates it, and only then changes public routing.

For the reasoning behind each step, read how to migrate documentation without losing SEO or GEO.

Phase 1: Establish the Baseline

• Export every indexable URL from the sitemap and a crawler.
• Export Search Console clicks, impressions, queries, and index status by page.
• Export analytics sessions, conversions, and landing pages.
• Identify pages with backlinks.
• Record current canonicals, titles, descriptions, and structured data.
• Save the current robots.txt and XML sitemaps.
• Record Markdown, llms.txt, MCP, OpenAPI, and other agent entry points.
• Capture current Core Web Vitals and representative Lighthouse tests.
• Identify forms, feedback tools, analytics, and support widgets.

Phase 2: Decide What Changes

• Keep the existing custom domain if possible.
• Keep high-value paths unchanged wherever possible.
• Assign each old URL one action: keep, rewrite, merge, redirect, or remove.
• Map every changed URL to one relevant final destination.
• Mark pages that should return 404 or 410 because no replacement exists.
• Confirm locale, version, asset, and trailing-slash behavior.
• Separate platform migration work from optional content redesign.

Phase 3: Build the Private Replacement

• Import or recreate all pages, images, code examples, and downloadable files.
• Rebuild navigation and page hierarchy.
• Preserve page intent, prerequisites, examples, warnings, and troubleshooting.
• Add one accurate canonical per indexable page.
• Recreate metadata and valid structured data.
• Validate internal links and anchors.
• Confirm mobile and accessible behavior.
• Configure search and analytics.
• Generate a clean sitemap from final canonical URLs.
• Validate machine-readable documentation outputs.

Phase 4: Test the Migration

• Crawl the private site and fix broken internal links.
• Test every redirect in the URL map.
• Ensure changed URLs redirect once to a 200 page.
• Remove redirect chains and loops.
• Test query parameters, versions, locales, uppercase paths, and trailing slashes.
• Confirm public pages are not blocked by authentication or robots.txt.
• Inspect rendered HTML rather than only the browser view.
• Compare representative old and new pages for content parity.
• Test forms, code copy, search, feedback, and API playgrounds.
• Test important pages from multiple devices and regions.

Phase 5: Prepare the Cutover

• Lower DNS TTL when required by the hosting change.
• Freeze old-site URL changes during the final migration window.
• Export a final content and URL snapshot.
• Prepare rollback instructions and name one decision owner.
• Verify the new production origin directly.
• Confirm SSL, custom domain, redirects, sitemap, and analytics.
• Schedule the launch when engineering and content owners are available.

Phase 6: Launch

• Change DNS or routing.
• Verify the homepage and several deep documentation pages.
• Verify old URLs redirect to the correct destinations.
• Confirm canonical tags use the public domain.
• Submit the final sitemap in Search Console.
• Inspect representative URLs in Search Console.
• Confirm analytics events and conversions are arriving.
• Monitor 404, 5xx, redirect, and crawler logs.

Phase 7: Monitor the First Month

• Compare clicks, impressions, indexed pages, sessions, and conversions to baseline.
• Review pages with the largest traffic decline.
• Fix unexpected 404 and soft-404 behavior.
• Check crawl stats and sitemap processing.
• Verify AI readers can still retrieve core tasks and examples.
• Review Core Web Vitals using field data when available.
• Keep permanent redirects in place for at least one year, ideally longer.
• Do not remove the old platform until rollback and content-export requirements are satisfied.

Migration Acceptance Criteria

Do not call the project complete until:

• every valuable old URL resolves or redirects correctly
• no canonical points at staging or the old platform
• the sitemap contains only final canonical URLs
• analytics and conversions work
• search and agent entry points return current content
• ownership for ongoing monitoring is explicit

If you are still deciding whether the move is worth it, use the documentation hosting cost calculator before the migration begins.