Checklist: documentation migration

Checklist

Written for a format migration (e.g. FrameMaker to DITA XML, or one static-site generator to another) - see migrating from FrameMaker to DITA XML for the source pattern this generalizes from.

Before migrating

• The old and new formats’ semantic capabilities are understood - migrating to a richer format (e.g. unstructured to DITA XMLDITA XMLA structured, modular XML authoring architecture built around the concept/task/reference typology and content reuse via conrefs and ditamaps.View in glossary →) costs more upfront than migrating to a poorer one, but pays back on content already in the richer format. See structured and unstructured formats.
• A small, non-critical content set is chosen as a pilot - not the whole corpus on the first attempt.
• URLs of existing pages are inventoried before anything moves, so redirects can be built from a complete list rather than reconstructed from memory afterward.

During migration

• Automated conversion (style-to-tag mapping, format conversion scripts) handles what it reliably can; manual restructuring is budgeted separately for what it can’t - don’t expect one pass to do both.
• Content is re-typed into its actual information typeInformation typingThe discipline of classifying content by its communicative purpose (concept, task, reference) rather than writing undifferentiated prose.View in glossary → (concept, task, referenceConcept, task, referenceDITA XML's three base information types: a concept introduces or explains an idea, a task is a numbered procedure, and a reference is lookup material like a parameter list. This manual's own articles are tagged with the same three types.View in glossary →) during migration, not just reformatted - splitting files without reclassifying them doesn’t produce genuinely modular content. See source format.
• A redirect is created for every URL that changes, old → new, before the old URL goes offline.

After migrating

• Every migrated page has been spot-checked against its original for lost content - diagrams, footnotes, and cross-references are the most common casualties.
• Old-format source files are archived, not deleted, until the new pipeline has been in production long enough to trust.
• Redirects are tested - not just written - by actually requesting a sample of the old URLs.
• Search indexes (full-text search, any AI-assistant index) are rebuilt against the migrated content, not left pointing at stale data.

Rollout

• The pilot set is validated end-to-end (create, update, publish) before migrating the rest of the corpus.
• Remaining content is migrated in batches small enough to review, not as one undifferentiated cutover.