Most DITA migrations do not fail loudly. They fail quietly, when a decision nobody was asked to make early turns into rework across thousands of topics later. This DITA migration checklist is ordered to prevent exactly that: decisions first, conversion second, validation as a gate rather than an afterthought. It is written for the documentation manager who has to run the project rather than admire it.
What a DITA migration checklist is actually for
A DITA migration is three projects wearing one name: a content project, a tooling project and a change-management project, running at the same time. Sequencing is the whole discipline. A checklist earns its keep by forcing the decisions that block conversion to the front, and holding back the work that can only sensibly follow them.
Read the list below as two halves. Steps 1 to 8 are decisions and produce documents; steps 9 to 14 are execution and produce content. If conversion at scale begins before step 8 is signed off, you are not migrating — you are manufacturing rework. The whole plan also assumes that conversion is rule-driven DITA conversion you can amend and re-run across the whole corpus, because a plan built on hand-conversion cannot survive its own review cycle.
The DITA migration checklist, step by step
- Name the open decisions and their owners. Before anyone touches content, list the rulings that block work while they stay open: DITA version and specialization, CCMS, topic-typing rules, metadata model, reuse strategy, style mapping, acceptance criteria. Give each a named owner and a date. Migrations rarely stall on conversion; they stall waiting for someone with the authority to say what a paragraph styled "Note — important" should become.
- Inventory the corpus — all of it, not the tidy part. Record every file, the tool that really produced it, its owner, when it last shipped, and whether it still needs to exist. Be precise about the tool, because it decides how much of your existing structure survives the move. Where a corpus is still a live authoring project, we read it the way its own tool reads it — so a Flare to DITA conversion hands your readers the same topic hierarchy they navigate today, rather than an order guessed from filenames. Where all that remains is published output, reading order has to be inferred from heading levels and folder order instead: a materially different job, and one you want to review deliberately rather than discover late. Use the audit to retire content as well — the cheapest page in any migration is the one you delete.
- Go and find the second pile. Behind every tool-managed corpus sits another one — scanned manuals whose source is long gone, vendor PDFs, Word files formatted by hand instead of by style, procedures living in a wiki. It is the pile that stalls migrations when it surfaces late — we have written about why — and it converts on a different path: a PDF has to be rebuilt into real document structure before it can become DITA, and a scanned page needs OCR before that. Hunt for the editable original before you settle for the print — an hour of searching a shared drive routinely saves a week of reconstruction.
- Decide the target: DITA flavour, specialization and CCMS. Base DITA or a specialization? Map or bookmap? A CCMS, or Git plus the DITA Open Toolkit? Decide before conversion, because the delivery shape — topic-per-file or composite, folder layout, filename and ID conventions, asset foldering — is a conversion setting, not a tidy-up afterwards. Output shaped for your platform drops in; generic output gets reorganised by hand.
- Write down the topic-typing rules. Decide how concepts, tasks, references and glossary entries are recognised, not merely that you want them. Good rules are mechanical: a body whose spine is an ordered list is nearly always a task; a parameter table is a reference. Then set the heading level at which a section becomes its own file, whether original IDs survive, and whether files are foldered or flat — exactly the choices that decide how one large composite file is split into topics, and exactly the ones that are painful to revisit once authors have started editing.
- Define the metadata model. Decide what every topic must carry — audience, product, release, lifecycle status, classification, index terms — and who supplies each value. Migration is the cheapest moment in a corpus's life to apply metadata, because folder structure, conditions and navigation still encode the context it can be derived from. After cutover, the same work is manual, topic by topic, forever.
- Agree the reuse strategy before conversion, not after. Decide what is reused by conref, what by key, and which legacy variables and reusable snippets should survive as keys rather than being flattened into their values — flattening is easy, silent, and irreversible without another migration. Decide where the shared library lives and how key scopes are drawn per publication. Then plan the pass that actually creates the reuse: duplicate topics, images and repeated blocks collapsed to one master with every reference rewritten, which is what Content Convergence does across a converted repository. Reuse retrofitted by hand later is the most expensive content work there is.
- Build the style-to-element map. The highest-value artefact in the project. Walk your source template, list every paragraph and character style actually in use, and name the DITA element and attributes each one becomes: a "Caution" style becoming a caution note, a numbered-procedure style becoming task steps. Do the same for conditional text and profiling. Every style you leave unmapped becomes a generic paragraph a human fixes later, one instance at a time. Where the mapping is configuration rather than bespoke work, an amendment is a re-run over the whole corpus instead of a rewrite — which is what makes review rounds converge rather than accumulate.
- Pilot on your worst content, not your best. Take the deepest nesting, the widest table, the most cross-referenced topic, the most heavily conditioned publication, and one item from the second pile. An easy pilot produces a plan that collapses the first time it meets hard content. Size the pilot so that every source type in the inventory appears at least once, and so the output is big enough to load into the real CCMS and publish from it, rather than merely opened in an editor and admired.
- Set machine-checkable acceptance criteria before the pilot output arrives. "Looks right" is not a criterion. Define done as: well-formed, valid against your DTD or schema, no broken links or cross-references, every conref and keyref resolving, every image reference present, no duplicate IDs or keys, no circular map chains. Run it across the whole repository rather than by spot check — a DITA completeness check that names the exact file and location of every issue turns validation into a work list instead of an investigation. Agree which categories block delivery and which are advisory.
- Design the review-and-iterate loop before review starts. Reviewers review; they do not hand-edit output. Every finding is triaged into one of three buckets: a mapping-rule change, a defect in the source content, or an accepted deviation. Rule changes are applied and the corpus is re-run, so one reviewer's finding fixes every instance of the problem at once. Timebox the rounds and expect more than one. A reviewer quietly repairing converted files is the most expensive failure mode in a migration, because those repairs vanish at the next re-run and nobody notices until the release.
- Plan links, images and assets as their own workstream. Decide what happens to internal cross-references, links between publications, and inbound deep links from the outside world that will break at cutover — which means a redirect map. Decide image naming, foldering and formats, which screenshots must be reshot rather than converted, who owns alt text, and where video and downloadable attachments live. Rule on orphans too: topics that exist but that no navigation references — your inventory and the validation sweep will surface them whether you planned for them or not.
- Model the translation impact in both directions. Reuse works in your favour: a warning that exists once is translated once, however many publications reference it. But migration also disturbs translation memory, because segmentation changes when a run-on paragraph becomes numbered steps or a table cell. Plan a memory re-alignment, freeze translation across cutover, decide whether the first structured release re-leverages or re-translates, and confirm your vendor handles DITA and XLIFF rather than only Word.
- Plan the cutover and the authors together. Cutover: freeze the legacy source, convert, validate, load, then publish once from DITA and diff that output against the last legacy build, so the differences are found by you rather than by a customer. Authors: an editor, a topic template per topic type, a one-page reuse rule card, and a style guide rewritten in terms of elements rather than fonts. Writers who never learn the typing and reuse model will faithfully rebuild unstructured content inside DITA, and the migration will have bought you nothing.
The inventory record behind every DITA migration plan
Step 2 is where most plans are thin, because a file count is not an inventory. These are the fields that later steps actually consume — capture them once, and the mapping, pilot and validation decisions largely make themselves.
| What to record | Why it matters | The decision it drives |
|---|
| Which tool genuinely produced each file | The tool people name is often not the one the content came out of | Which conversion path applies, and how much existing structure survives |
| Whether the source still carries its own table of contents | Determines whether reading order is authoritative or has to be inferred | Whether structure comes from headings and folder order instead |
| Conditions, variables and reusable snippets in use | This is the reuse model your legacy tool already gave you, for free | What becomes profiling, what becomes keys, what is resolved to text |
| Styles actually used, not styles defined | A template always defines far more styles than anyone ever applied | The true scope of the style-to-element map |
| Assets: images, video, attachments, formats | Assets outnumber topics and break silently | Foldering, naming, the reshoot list, alt-text ownership |
| Lifecycle: owner, last shipped, still current | Dead content costs exactly as much to migrate as live content | Retire, convert or archive |
| Localisation status and target languages | Reuse and segmentation both hit translation memory | Re-alignment, freeze window, vendor requirements |
Where DITA migration plans go wrong
- Converting before the style-to-element map exists, so the first review round rediscovers the mapping one comment at a time.
- Choosing the CCMS after conversion, then reshaping delivered output by hand to fit it.
- Piloting on clean, shallow, recently written content that proves nothing.
- Treating validation as a final inspection rather than a gate run at every iteration.
- Letting reviewers edit output instead of amending rules.
- Discovering the second pile — the scanned and unstyled legacy — after the schedule is fixed.
- Flattening legacy variables and reusable snippets into plain text, quietly throwing away reuse you already had.
- Budgeting for conversion but not for author training, so the old habits reappear in the new format.
None of these are technical problems, which is why a checklist beats a tool. Insist on one non-negotiable throughout: content conservation. Structure may degrade gracefully on genuinely ambiguous source, but text is never silently dropped — anything a converter cannot type correctly should arrive flagged, not missing. If you are scoping the work rather than running it yet, start with the case for migrating to DITA at all, then bring the inventory above to a conversation about DITA migration services, so the estimate is built on your real corpus instead of an average one.
Frequently asked questions
What should be on a DITA migration checklist?
Two halves, in order. First the decisions: owners and deadlines, a full corpus inventory, the legacy content nobody mentions, the target DITA flavour and CCMS, topic-typing rules, the metadata model, the reuse strategy, and the style-to-element map. Then the execution: a pilot on hard content, machine-checkable acceptance criteria, a review-and-iterate loop that changes rules rather than files, an assets and links workstream, the translation impact, and cutover plus author training. The order is the value — every execution step depends on a decision above it.
What are the main DITA migration steps, in order?
Inventory and audit, find the unstructured legacy pile, choose the target DITA flavour and CCMS, define topic typing and metadata, agree the reuse strategy, map styles to elements, run a representative pilot, validate against your own schema, iterate by amending rules rather than editing output, handle links and assets, plan translation, then cut over and train authors. Conversion itself sits inside that sequence rather than at the start of it, which is the single most common planning mistake.
How long does a DITA migration take?
There is no honest generic answer, but there is an honest list of what moves it: the number of distinct source types, how much of the corpus is unstyled or scanned rather than tool-managed, how many styles and conditions are genuinely in use, whether a specialization and metadata model already exist or must be designed, how many review rounds your organisation needs to reach sign-off, and whether the content is localised. Corpora that are large but uniform move faster than small ones assembled from many tools and eras.
Should I clean up content before or after DITA migration?
Retire before, restructure after. Deleting obsolete content before conversion is pure saving. Fixing genuine defects in the source — wrong facts, broken procedures — belongs at source while the authors still own it. But structural cleanup such as deduplication, topic typing and consistent element use is cheaper after conversion, because it can be applied as a rule and re-run across the whole corpus rather than performed by hand in the legacy tool.
How do I pick pilot content for a DITA migration?
Deliberately pick the content people would rather avoid: deepest heading nesting, widest and most merged tables, the most heavily cross-referenced topic, the most conditioned publication, and at least one item from the unstyled or scanned pile. Cover every source type in the inventory at least once, and make the pilot large enough to load into the real CCMS and publish from it. A pilot on easy content produces confidence rather than information.
Related conversions
Send us 25 pages. The messier, the better.
We'll convert them to DITA free of charge — through the real pipeline, not a demo —
and review the output with you. Then we'll discuss pricing one-to-one.
Request your free sample conversion