Documentation migration checklist for SaaS teams

This is the checklist we work from when a SaaS team moves its documentation off Zendesk, Confluence, Word or Google Docs and onto a docs-as-code stack such as Docusaurus, MkDocs or GitBook. It is ordered by phase, every item is something you can verify, and each phase ends with a gate: if the gate is not met, the next phase waits.

A checklist is only useful if it is honest about sequence. Most migration trouble comes from doing a later item early (choosing a theme before counting pages) or an early item late (building the redirect map the week of launch). So the phases below are strict. You can run items inside a phase in parallel; you should not start a phase while the previous gate is open.

If you want the reasoning behind a phase rather than the list, each section links to the longer piece that explains it.

Phase 0: Decide whether to migrate at all

Not every documentation problem is a platform problem. Before anyone exports anything, confirm the move is worth it.

• The problem is written down in one paragraph, in terms a support lead or CFO would recognize: cost, lock-in, broken workflow, search quality, or a support bot that cannot use the content.
• Someone has checked whether the current platform can fix that problem with configuration. If it can, stop here.
• The exit cost of the current platform is understood: export formats, URL control, and what breaks when the account closes. Our post on documentation vendor lock-in covers how to price that.
• A single executive sponsor has agreed to the move and to the date range.
• One person owns the migration day to day. Not a committee, a name.

Gate: a one-page decision note, signed off by the sponsor. The handbook page on deciding whether to migrate has a template for it.

Phase 1: Inventory and audit

The inventory is the input to every later phase. The redirect map, the information architecture, the estimate and the cutover date are all projections of it.

• Every source page has one row: source URL, title, owner, last meaningful edit, twelve-month traffic, and locale.
• Every row has exactly one decision: migrate, merge, rewrite, move, cut, or escalate.
• Duplicates and contradictory pairs are listed separately, each with a named decision owner.
• Pages with restricted visibility are flagged. Internal content published by accident is a disclosure problem, and a public docs site is not the place to discover it.
• Attachments, embedded videos and downloadable files are counted, not estimated.
• The page count is agreed, because it drives scope. For reference, our own documentation migration projects are priced from $4,500 for up to 150 pages and from $9,500 for up to 500 pages, and the count is the first thing we confirm.

Gate: counts per decision category add up to the total, and every row has a name next to it. The content audit post walks through the categories.

Phase 2: Design the target

Design the new site from the surviving pages, not from the old navigation. The old navigation is usually the org chart from three reorganizations ago.

• Content types are defined: at minimum concept, task, reference and troubleshooting, each with a template.
• The top-level navigation is drafted from the inventory's surviving rows and tested against the ten most common support questions.
• URL rules are written down: lowercase, hyphenated, no dates, no internal team names, no file extensions, one convention for trailing slashes.
• Vocabulary is settled for the product's core nouns, so the new site does not inherit three names for the same feature.
• The platform is chosen against the requirements that actually came out of the inventory: versioning, localization, search, authoring model. If you are still choosing, we compared the options in Docusaurus vs MkDocs vs GitBook for help centers.
• Metadata fields are defined: owner, product area, audience, plan tier and, if support bots will read the content, anything they need to filter on.

Gate: a target sitemap where every surviving inventory row has a target path.

Phase 3: Convert and normalize

Conversion is the visible part and rarely the part that fails, as long as it is scripted.

• Conversion is a script in the repository, not a manual copy-paste, so it can be rerun when the source changes during the project.
• Vendor markup is stripped: layout tables, inline styles, macro wrappers, generated anchor IDs.
• Platform-specific blocks are mapped to the target's equivalents, for example callout panels to admonitions and expand macros to collapsible details.
• Images and attachments are downloaded, renamed predictably and stored next to the pages that use them, with alt text.
• Internal links are rewritten to the new paths from the target sitemap, not left pointing at the old host.
• Headings are normalized so each page has one title and a clean hierarchy underneath it.
• A content freeze window on the old platform is agreed, with a named person approving any emergency edits during it.

Gate: a full build of the new site from the converted content, with zero broken internal links. The handbook's converting to Markdown page covers the scripting side.

Phase 4: QA

QA is where you find out whether the conversion script told the truth.

• The build fails on broken internal links and broken anchors.
• A sample of pages from every content type has been compared side by side with the source by someone who knows the product.
• Tables, code blocks and numbered procedures have been spot-checked on every template, because they are where converters fail quietly.
• Search returns the right page for the top support questions.
• Keyboard navigation, heading order, color contrast and image alt text have been checked against WCAG 2.2 AA.
• Page titles and meta descriptions exist on every page and are unique.

Gate: QA findings are either fixed or logged with an owner and a date. The handbook page on QA and link checking lists the automated checks we run.

Phase 5: Redirects and cutover

This is the phase that breaks when it is rushed. Treat the redirect map as a deliverable with its own tests.

• The source URL list is built from the sitemap, analytics, server logs, search console data and a crawl, deduplicated.
• Every source URL has a target and a reason. No row points at the site root.
• Redirects are permanent (301), one hop, and tested against staging with a script.
• The support team's macros, in-product help links and onboarding emails have a list of URL changes and a date to update them.
• DNS or origin changes are scheduled for a low-traffic window with the person who can roll them back on call.
• The new sitemap is ready to submit on the day.

Gate: the redirect test passes against production within minutes of the switch. The long version is in redirect mapping for docs migrations.

Phase 6: After cutover

A migration is finished when the new system is easier to run than the old one, not when the DNS changes.

• The old platform is read-only, then closed on a date everyone knows.
• Section owners are recorded in the repository, for example in a CODEOWNERS file, so reviews route themselves.
• Contributors have made their first real pull requests with someone pairing, not just read a guide.
• A runbook covers building, previewing, publishing, upgrading dependencies and adding redirects.
• Search console coverage and 404 logs are reviewed weekly for the first month.
• Rewrites deferred from Phase 1 are in a backlog with owners.

We wrote a separate piece on what outlasts cutover, because ownership and handover are where migrations quietly fail months later.

How to use this checklist

Copy it into an issue or a project board, one issue per phase, and paste the gate into the issue description. Keep the checkboxes honest: an item is done when someone else can verify it, not when the person doing it feels finished.

If you want a second pair of hands on any phase, or the whole move, our documentation migration service follows this exact sequence, with a 30-day fix window after delivery. Send us a short description of your current platform and page count through the contact page. We reply within 1 business day.