Field Guide
Converting Word to DITA or S1000D
The Short Answer
Clean First, Convert Second, Validate Last
Word to DITA or S1000D is a pipeline, not a file format change. You inventory the library, clean the styles, cut the content into topics or data modules, run an automated mapping, fix what the mapping could not decide, merge the duplicates, and validate. The order matters because each step makes the next one cheaper.
This page is the method. For the argument about why big Word files fail, see why Word breaks at scale; for what authors do afterward, see Word with guardrails. If your source is FrameMaker, read FrameMaker to DITA or S1000D instead.
Why Word Is Hard
Five Places the Structure Is Missing
- Styles used as suggestions
- A style name says how a paragraph was meant to look, and any author can override it with direct formatting. Two paragraphs that look identical may carry different styles, and two with the same style may have been meant differently. The converter can only map what the style says.
- Numbering typed by hand
- Steps, figure numbers, and cross-references that were typed rather than generated are plain text. A converter cannot tell that "3." is the third step and not a number in a sentence, and a typed reference to "Figure 4" points at nothing a system can resolve.
- Tables doing layout work
- Word tables hold data, but they are also used for side-by-side text, indented warnings, and spacing. Merged cells and nested tables then have to be split into the table model of the target, and a layout table has to become something that is not a table at all.
- Images embedded in the body
- Pictures sit inside the file as anchored or inline objects, often pasted from other tools, with the caption as a separate paragraph nearby. Each needs to leave the file, get a managed name, and be tied back to its caption and its place in the text. A figure drawn with Word's own tools has to be redrawn or exported.
- Tracked changes and comments
- Old insertions, deletions, and review comments are still in the file. Convert them as they stand and the output may carry text that was meant to be deleted. Someone has to decide, before the run, whether each pending change is accepted, rejected, or kept as history elsewhere.
FrameMaker libraries tend to be built on a template that was enforced. Word libraries often were not, so the same five problems appear at random through the files instead of in a few known places. That is why a sample from the worst files tells you more than a sample from the best.
Decide First
The Model and the Rules Come Before the Run
A converter maps from something to something. If the target is undecided, the mapping is a guess, and it gets redone. Settle three things before anyone runs a file.
The target. A contract that calls for S1000D decides it. Content reused across several product deliverables often argues for DITA. See S1000D versus DITA if it is still open.
The information model. In DITA, choose which topic types you will use. The 1.3 specification describes a concept as the topic that answers what something is, a reference as facts about a product, and a task as how to do something in order. A task comes in a general model and a strict model, and the strict one is applied through a constraint, which is a rule you choose, not a default you inherit. In S1000D, choose which data module types the library needs; our tour of the S1000D data module types and the DITA topic types show what each carries.
The rules on top. For S1000D, the project's business rules, expressed as a BREX, say what is allowed in each module. Get the BREX from the customer or prime before conversion; see what a BREX is. For DITA, decide your constraints and any specialization now, because they change what a valid topic is.
The Steps
Six Steps, in This Order
- Inventory. List every file, its owner, its revision state, and whether it is still maintained. Mark the ones that share content, because the same warning or procedure copied into several files is a reuse candidate. Settle which files are not converted at all; our convert-or-ingest guide covers that split.
- Style cleanup. Do the cleanup before the run, in Word, where a find-and-replace on a style is cheap. Strip direct formatting, merge duplicate styles, turn typed numbering into list styles, and accept or reject tracked changes. Each fix here removes a class of manual correction after conversion.
- Chunk into topics or data modules. Decide where each file splits and what each piece is. In DITA that means one topic per idea, typed as concept, task, reference, or another type. In S1000D it means one data module per unit of information, each with a type and a data module code. Heading levels are a starting guess; the real boundary is a unit a reader could use alone.
- Automated conversion, then manual cleanup. Run the cleaned files through a mapping from styles to elements, and review what comes out. Automation does the repetitive part. People handle what the mapping cannot decide: ambiguous paragraphs, tables, and figures. Feed the repeated fixes back into the mapping and rerun, so the manual share shrinks each pass.
- Reuse pass. Compare the converted pieces and replace near-duplicates with one source. In DITA that is content references and keys; in S1000D it is shared data modules and applicability. Do this after chunking, because reuse needs small units, and decide which copy is the master before you merge.
- Validation. Check every output against the schema first. Then check against the rules that sit on top: the constraints of your DITA setup, or the project BREX for S1000D. Last, render a sample and compare it with the Word original, so a reviewer can confirm that nothing was dropped on the way.
Tooling
What the Publishing Toolkit Does Not Do
A common assumption is that the DITA Open Toolkit takes in Word and gives out DITA. Its documentation describes tools for processing content that is already authored in DITA, and the input formats it names are DITA XML and Markdown. It is the publishing end of the line, covered in the DITA Open Toolkit explained.
The Word end needs its own mapping from styles to elements, and a person to review what it produces. Treat any tool that promises a clean result without a review pass with caution, because the missing information is not in the file for any tool to find. The checks in our structured content readiness checklist are worth running before you choose one.
Estimating
Size the Work Without a Page Count
Page count is the multiplier, not the driver. What moves the effort is how consistent the styles are, how many tables carry layout, how many figures need rework, how much is duplicated, and how strict the target rules are. None of those can be read off a file count.
So estimate from a sample. Pick a small set that includes the worst files, run the full pipeline, and record what share converted untouched, what kinds of correction remained, and how long each kind took. Scale from that, family by family. The ranked drivers are in what drives S1000D conversion cost. Also count the people cost nobody budgets: the colleague who is the Word help desk usually knows where the worst files are.
Shakewell converts Word and FrameMaker libraries to DITA and S1000D.
FAQ
Questions We Hear
Can I convert a Word file to DITA automatically?
Partly. A .docx file is XML inside a package, so a program can read it, and a mapping from styles to elements can produce topics. What automation cannot supply is the decision about where to split, what type each piece is, and what the author meant by an inconsistent style. Plan for automated conversion followed by review, not a one-click result.
Does DITA-OT convert Word to DITA?
Not as its documentation describes it. The DITA Open Toolkit is described as tools for processing content already authored in DITA, and the inputs it names are DITA XML and Markdown. It is the publishing step that comes after conversion. The Word-to-XML step needs its own mapping and tooling. Our guide to the DITA Open Toolkit explains what it does do.
Which topic type should each Word section become?
Ask the question each type answers. The DITA 1.3 specification describes a concept as answering what something is, a task as answering how to do something in order, and a reference as documenting facts about a product. A section that explains becomes a concept, a numbered procedure becomes a task, and a table of values becomes a reference. Our guide to DITA topic types has examples.
What changes when the target is S1000D?
The unit becomes the data module, with a type and a code, and the project's business rules decide what is allowed inside it. That makes the BREX a decision to settle before conversion rather than a check afterward. Read what a BREX is, and ask the customer or prime for the rules in force, because the Word files cannot tell you.
How do I estimate the effort for a Word library?
Do not use page count alone. Convert a small sample that includes the worst files, then record how much needed manual correction and what kind. The cost drivers are structural: style discipline, table complexity, graphics, and how many pieces are duplicates. Those are properties of your files, which is why a sample is better evidence than a rule of thumb.
Should I convert at all, or keep authoring in Word?
That depends on whether the content has a future. Documents that will be revised, reused across deliverables, or delivered under a structured standard repay conversion. Documents that are settled may be better served as they are. The convert or ingest guide sets out how to decide document family by document family.
Get In Touch
Start With a Sample of Your Worst Files
Send us a few Word manuals, including the ones nobody wants to touch, and the target you have in mind. We will tell you what the conversion involves.