Decision guide
DITA conversion turns content authored in another format into DITA. DITA migration moves an entire body of documentation into production-ready DITA inside a CCMS, and is run as a project. DITA transformation is everything done with content once it is already in DITA: reshaping it, and publishing it out to other formats. The three words are often used as if they meant the same thing. They differ in scope, in who has to decide what, and in when the work counts as finished.
Three definitions
DITA conversion
DITA conversion is the process of turning content authored in another format, such as MadCap Flare, Word, FrameMaker, HTML or PDF, into DITA, the OASIS open standard for topic-based technical content. Done well, it rebuilds what the content means, not how it looked: headings become a topic hierarchy, procedures become tasks, tables become CALS tables, and reuse is expressed with conref and keyref. The unit of work is a source format and the converter built for it. See DITA conversion services; every format we convert is listed under document conversion services.
DITA migration
Anyone can run a converter over a folder and get XML out. A migration is the disciplined move of an entire content estate from a legacy tool into production-ready DITA inside your CCMS, with the structure, reuse, conditions and metadata your team depends on. It is a project with a review loop: analysis, a reviewed pilot, iteration, conversion at scale, validation and delivery. Conversion is the engine inside it. See DITA migration services.
DITA transformation
Conversion gets your content into DITA. Transformation is everything you do with it afterwards. It runs in two directions: reshaping DITA between its own structures (one composite document, or many topics), and publishing DITA out to DocBook, Markdown and PowerPoint. Our guides keep one inbound case with it: structured content that is not quite documentation, a slide deck for instance, brought into DITA (PowerPoint to DITA conversion). See DITA transformation services.
Side by side
| Aspect | Conversion | Migration | Transformation |
|---|---|---|---|
| Scope | One source format, through the converter built for it | An entire content estate, with its structure, reuse, conditions and metadata | Content that is already in DITA (plus one inbound case: slide decks) |
| Input | A Flare, RoboHelp or FrameMaker project, Word files, HTML, Markdown, DocBook, PDF | Everything the documentation team owns, often in several formats and conditions | DITA topics and maps, or a composite DITA document |
| Output | Valid DITA: topics, a map or bookmap, topic-per-file or composite | Typed DITA in your layout, a map or bookmap and a key map, collected assets and a validation report, in your CCMS | DocBook articles, Markdown, a Markdown docs tree or a PowerPoint deck; or the same DITA in another shape |
| Who decides what | A generic run infers structure. A customer-specific run applies your style mapping, profiling scheme, reuse strategy, naming and DTD | You and the migration team, in a reviewed pilot: how styles become elements, which topic types you want, how conditions and reuse are handled, the ID and folder conventions | Decisions set once per transform, so the same construct is treated the same way in every document |
| Finished when | The output clears the completeness check and is delivered in the structure your platform expects | The content is imported, valid and accepted in your CCMS | The output is generated. When the source changes, you regenerate it; you do not rewrite it |
Which one do you need? Five cases
1. One documentation set in one source format
You have a Flare project, or a set of Word manuals, and a DITA model to put it in. That is a conversion. Start from the guide for your format in the DITA conversion guides, and decide early whether a generic run is enough or you need a customer-specific one.
2. A whole documentation estate and a CCMS to fill
Several products, years of content, a platform to load. This is a migration. The converters matter less than the decisions: how your styles become semantic elements, how conditions and reuse are handled, what the IDs and folders look like. Those are agreed in a pilot and then applied the same way to the thousandth document as to the first. What acceptance on import takes is covered in DITA CCMS migration.
3. A mixed archive with scans and old PDFs
Also a migration, but one that must be scoped as two piles. Content that still carries machine-readable structure converts predictably. Scans and unstyled PDFs have to be rebuilt first, and should not hold the rest hostage. See legacy content migration for the split and scanned PDF to DITA conversion for the hard pile.
4. Content already in DITA, readers somewhere else
Your source is DITA, but an audience needs a Markdown docs site, a DocBook-based platform or a slide deck. That is transformation: the same single source published to another format, as an output you regenerate and not a copy you maintain.
5. DITA in the wrong shape
A migration landed as one enormous composite file and you want a reusable topic library, or you have split topics and a reviewer or translator wants one self-contained file. That is also transformation: split DITA into topics, or merge DITA topics into one file.
How the three fit together
They are layers more than alternatives. A migration contains conversions: the project method settles the mapping, and the converters apply it. Transformation starts where both end.
The discipline underneath is the same in all three. Content conservation is enforced: structure may degrade gracefully and be flagged for review, but text is never dropped. The same content in gives the same output, every time. And the result is validated across the whole repository before delivery. If you are not sure which of the three your content needs, send 25 pages: the free DITA conversion sample shows what your content becomes before anything is agreed.
Frequently asked questions
Is DITA conversion the same as DITA migration?
No. Conversion turns content from one source format into DITA. Migration moves an entire body of documentation into production-ready DITA inside a CCMS and is run as a project: it settles how your content maps to structured elements, converts at scale, validates the result against your schema and delivers content your writers can author against. A migration contains conversions; a conversion on its own is not yet a migration.
How is DITA transformation different from DITA conversion?
Conversion brings content from another format into DITA. DITA transformation is the work you do with content once it is in DITA: reshaping it between DITA's own structures (one composite document, or split topics) and publishing it out to other formats such as DocBook, Markdown and PowerPoint. Our transformation guides also cover one inbound case, slide decks into DITA.
Is DITA to Markdown or DITA to DocBook a conversion or a transformation?
A transformation: the content is already in DITA and is being published to another format. In everyday use people still say "DITA to Markdown conversion", and our guides keep that name.
Do we need a migration project for a small documentation set?
Not necessarily. A generic conversion gives you valid, well-formed DITA with inferred structure, which is a correct starting point. The project method earns its place when the content has to land in a CCMS with your own styles, conditions, reuse strategy and naming conventions, because those are decisions, not file operations.
When is a migration finished, and when is a conversion finished?
A migration is finished when the content is imported, valid and accepted in your CCMS, not when files are delivered to a folder. A conversion is finished when its output clears the completeness check and is delivered in the structure your platform expects.
Related guides
- DITA conversion services: convert any legacy source to clean, valid DITA
- DITA migration services: legacy documentation into your CCMS
- DITA transformation services: into, out of, and between DITA
- The DITA migration checklist: 14 steps, in order
- See the output on your own content: free 25-page sample
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.
Get your free 25-page sample