Migrating legacy documentation to DITA XML is one of the most complex projects a documentation team can undertake. Done well, it transforms your content into a structured, reusable asset. Done poorly, it creates a DITA-shaped version of the same problems you had before.
Phase 1: Content audit and assessment
Before writing a single line of XSLT or opening a migration tool, you need to understand what you have. Catalogue all existing documentation: file formats, file counts, approximate word counts, languages, and the systems they currently live in. Assess content quality and identify reuse candidates.
Phase 2: Information architecture design
The information architecture defines how your content will be structured in DITA. Define your topic types — concept, task, reference — and whether you need specialisations. Design your map structure and define your metadata model for filtering and conditional processing.
Phase 3: Migration approach and tooling
There are three broad approaches: automated conversion, semi-automated conversion with manual cleanup, and manual rewriting. The right approach depends on the volume, quality, and structure of your source content. Semi-automated with manual cleanup is the most common approach.
Automated conversion tools
Tools such as oXygen XML Author batch conversion and Migrate (formerly Stilo Migrate) can convert Word, HTML, and FrameMaker content to DITA automatically. Automated conversion is fast for large volumes but produces DITA that reflects the structure of the source.
Phase 4: Validation and quality assurance
DITA migration produces a large volume of new content quickly. Validate against your information architecture, check for broken references and missing metadata, and conduct a representative sample review before declaring the migration complete.
Phase 5: Publishing pipeline and go-live
Before going live with migrated content, verify that your publishing pipeline produces the expected outputs. Test all output formats, check that conditional processing works correctly, and confirm that the migrated content integrates with your CCMS and authoring workflow.
A successful DITA migration requires investment in planning, architecture design, and quality assurance — not just conversion tooling. Treat it as a content improvement project, not just a format conversion exercise.