Decision guide
In-house DITA conversion works when the corpus is small, consistent and comes from a structured source, and when someone on the team has time to learn the tooling. It stops working at scale, because the hard parts are not the conversion itself: they are maintaining the mapping as you learn, handling conditions and reuse, validating at repository scale and getting the content accepted in the CCMS. The one-chapter test below turns the question into an estimate.
When in-house DITA conversion works
- The corpus is small. Few publications, and few content families.
- It is consistent. One tool, one template, styles applied the way the template intended. Corpora that are large but uniform move faster than small ones assembled from many tools and eras.
- The source is structured. It still carries its structure in a form a machine can read: a tool project, styled Word documents, structured HTML or Markdown. Unstyled documents, PDFs and scans are a different job, because their structure has to be rebuilt first. Our guide to legacy content migration explains that split.
- Someone has time to learn the tooling. That means the target model as well as the converter. The DITA learning curve comes twice: once for the syntax, and again for the reuse and topic typing model.
The one-chapter test
Convert one difficult chapter yourself before you decide. What that takes, multiplied by your content families, is your real in-house estimate. Run it the way a vendor pilot should be run.
- Pick the chapter you would rather avoid. The one with the dense specification tables, the topic tangled in conditions, the file with snippets inside snippets, the scanned appendix.
- Write the acceptance criteria first. 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.
- Convert it to the real target. Topic-per-file or composite, your naming and folder conventions, your profiling scheme.
- Validate it and load it. Run the validation against your own schema, then import the result into a sandbox CCMS.
- Ask an author to edit a converted topic. Five minutes in your own editor exposes generic infotypes, wrong note types and broken reuse faster than any report will.
- Change one mapping decision and convert again. If the change means repeating hand work, your review rounds will accumulate instead of converge.
- Multiply. Take what the chapter cost, from first attempt to accepted in the sandbox, and multiply it by your content families. Your inventory supplies that count: which tool really produced each file, and which styles and conditions are in use. The DITA migration checklist lists the inventory fields to record.
The three usual routes, and where each leaves you
Most teams clear the migration barrier in one of three ways.
| Route | Where it stops |
|---|---|
| Manual migration, by your own writers or by a services firm working by hand | Slow, expensive and inconsistent between writers. A person migrating topic by topic mis-maps styles, misses the files nobody remembers, and silently drops a snippet nested three levels deep inside another snippet. |
| A one-off script | Handles the easy 80% and breaks on snippets and conditions, or on the next oddly styled document. Somebody has to maintain it after the developer who wrote it leaves. |
| A desktop utility | Ignores project structure and walks the published HTML, or converts one file at a time with no memory of house style. |
All three leave you with generic output and weeks of cleanup. Generic output is real DITA: valid and well-formed, with inferred structure, generic topic types, generated IDs and the source's own style names. It is not yet your DITA. The difference between a generic and a customer-specific run is set out in the DITA conversion services overview, and the Word to DITA conversion guide shows the same three routes for a single format.
What scales badly
Four things do not scale with the conversion itself.
Maintaining the mapping as you learn
The style-to-element map is the highest-value artefact in the project, and every review round changes it. Where the mapping is configuration, an amendment is a re-run over the whole corpus. Where it lives in hand edits, reviewers repair converted files one at a time, and those repairs vanish at the next re-run.
Conditions and reuse
Flattening conditional text into plain paragraphs produces output that validates perfectly and destroys your single-sourcing. Flattening variables and reusable snippets into their values is easy, silent, and irreversible without another migration.
Validation at repository scale
The check inside an editor is interactive and desktop-sized: it covers the project a writer happens to have open. A migration needs the whole repository checked in one run, and checked again after every fix: links, conref, keyref, image references, duplicate IDs and keys, circular maps, and table grids, a check no DTD can express. That is the job of a DITA completeness check.
Acceptance in the CCMS
Valid DITA on disk is not content accepted by the platform. The import gate fails late, in bulk and usually silently, and nearly every failure has to be fixed upstream in the conversion. Our guide to CCMS migration lists what the gate checks.
The middle way: convert on the same platform yourself
The choice is not only between writing your own tooling and handing everything over. DocentraX can be used in two ways: as a managed migration, or by converting on the same platform yourself. Every migration runs on the DocentraX conversion portal at convert.docentrax.com, and your team can use the same conversion platform for its own conversions once the migration is done. Each converter there is a versioned module with job logs, validation reports and repeatable results.
If you outsource, set the same test
A vendor should pass the test you set yourself: your worst chapter, your schema, your sandbox, one correction request. Ask how a defect found in review is corrected, by hand-editing one file or by amending the mapping and re-running the corpus, and whether re-runs are billable. The full question set is in how to choose a DITA conversion vendor, and what moves the price is in the guide to DITA conversion cost.
You can start that test with us at no cost: the free 25-page sample converts up to 25 pages of your own documents through the production pipeline.
Frequently asked questions
When does in-house DITA conversion work, and when does it stop?
In-house works when the corpus is small, consistent and comes from a structured source, and when someone has time to learn the tooling. It stops working at scale. Convert one difficult chapter yourself first: what that takes, multiplied by your content families, is your real in-house estimate.
Why do in-house DITA conversion scripts stall?
A one-off script handles the easy 80% and breaks on snippets and conditions, or on the next oddly styled document. Mapping decisions you can read and adjust survive staff turnover far better than one-off scripts.
Can we do part of a DITA conversion ourselves?
Yes. DocentraX runs as a managed migration, or you convert on the same platform yourself, and your team can use that platform for its own conversions once a migration is done.
Related guides
- How to choose a DITA conversion vendor
- DITA conversion cost: what actually drives the price
- The DITA migration checklist: 14 steps, in order
- DITA conversion services: convert any legacy source to clean, valid DITA
- 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