Field Guide
DITA Migration: What the Conversion Doesn't Cover
The Gap
Conversion Moves Content, Not People
A conversion turns Word, FrameMaker, or legacy XML into valid DITA topics and maps, and a good vendor does it well. What a conversion cannot do is change how your writers work. The day converted content lands in the CCMS, every future edit is made by people who learned their craft writing books.
That is where migrations drift. A writer who thinks in chapters adds a procedure to a concept topic, because that is where it used to live. A warning gets copied into forty topics instead of referenced once. A product difference is written into the text instead of marked as a condition. Every one of those edits validates. A year later the library is valid DITA without the reuse, filtering, or consistency that justified the move.
Training
One Model, Taught to Each Role
DITA training is not tool training. Tool training shows your team how to open, edit, and check in a topic. DITA training teaches the model underneath: when content is a task and when it is a concept, how a map assembles a deliverable, and how keys and content references make reuse work. Each role needs a different depth of it:
- Authors
- Topic types and information typing, writing a task that is only a task, minimalism, and reaching for keys and content references instead of copying.
- Information architects
- Map structure, key naming and scope, reuse strategy, conditional attributes, and when (rarely) to specialize.
- Reviewers and subject matter experts
- How to review a topic rather than a book, and what a requested change means when the content is reused in ten places.
- Managers
- What the model makes measurable, where the effort goes after go-live, and what to staff.
Timing matters more than most plans allow for. The best moment is after a sample of your own content has been converted and before authors start editing the rest, so the exercises use your topics and the habits form on the new model rather than the old one. For a head start, our explainers cover topic types and maps, keys, and conref.
Several Groups
Several Teams, One Library
Migrations often bring more than one documentation group into the same system: two divisions, several plants, product lines that grew up separately. Each arrives with its own templates, terms, and habits. The migration is the one moment they can agree on a shared model, and these decisions are far cheaper to make together now than to reconcile once the content is merged:
- Topic rules
- Which topic types are in use and what constraints apply, so a task written by one group reads like a task written by another.
- Keys
- Naming conventions, and where shared keys (product names, part numbers, contact details) are defined and who may change them.
- The shared reuse library
- Which warnings, safety statements, and common procedures are written once, where they live, and who owns them.
- Conditions
- One set of attributes and values for product, model, audience, and region, and the DITAVAL files that apply them. Two groups filtering on different vocabularies cannot share a topic.
- Style and terminology
- One style guide and one term list, or a reader meets two companies in the same manual.
- Workflow
- How review and release run, and what happens when a change to shared content lands in another group's publication.
Training the groups together, from one curriculum, is the simplest way to get these decisions made consistently. Groups trained separately tend to decide separately, and the result is two libraries sharing one CCMS.
Delivery
Where the Output Goes
A DITA pipeline ends at an output: a PDF or an HTML5 build from the DITA Open Toolkit or the CCMS. Service technicians, dealers, and customers need more than a file. If the build lands on a share drive or goes out as an email attachment, the migration has rebuilt the problem PDFs create with better source files.
Delivery is worth planning before the migration finishes, because the source decides what delivery can do. Filtering by model, access scoped to an audience, and search that returns the right procedure all depend on metadata the topics carry, and that metadata is cheapest to add while content is being converted. Delivery is also the part we build: the Content Portal is a searchable, version-controlled destination for technical content, scoped to exactly who should see it.
Planning
What to Put in Next Year's Budget
Roadmaps budget the conversion carefully and the rest loosely. For the stretch from the last converted batch to a team running on its own, these are the lines worth planning:
- Training for every role
- A shared foundation for everyone who touches the content, and a deeper track for the people who will design maps, keys, and reuse.
- Coaching through the first releases
- The first real updates, reviews, and publications on the new model are where the questions no course anticipated come up.
- Governance time
- A named owner, with hours set aside, for the shared model, the reuse library, and the conditions. Without one, the decisions above erode.
- Publishing maintenance
- The PDF and HTML plug-ins are maintained assets: every toolkit upgrade and branding change lands there.
- Delivery
- A destination for the output, and the metadata work that makes it useful to the people reading it.
None of them is as visible as the conversion itself, and all of them are cheaper planned than discovered.
FAQ
Questions We Hear
When should a team get DITA training during a migration?
After a sample of your own content has been converted and before authors start editing the rest. Earlier, the training runs on examples your team will never see again; later, it has to correct habits already formed in the new library.
Is tool training the same as DITA training?
No. Tool training teaches the editor and the CCMS: opening, editing, checking in, publishing. DITA training teaches the model those tools implement: information typing, maps, keys, content references, and conditions. A team can be fluent in the tool and still write topics that defeat reuse.
How do several divisions share one DITA library?
By agreeing on the shared parts before content is merged: topic rules and constraints, key naming, a reuse library with a named owner, one set of conditional attributes and values, and one style guide. Training the groups together from one curriculum is the simplest way to get those decisions made the same way.
Do we need DITA specialization?
Usually not at first. Start with the standard topic types and use constraints to narrow them to what your content needs. Specialize when a real, repeated structure has no good home in the base types, because every specialization is something your tools, plug-ins, and training carry from then on.
Should we wait for DITA 2.0?
No. DITA 2.0 is not yet an approved OASIS standard. DITA 1.3 is the current specification and the one production tools are built for, so migrate to 1.3 and treat 2.0 as a later, planned upgrade.
Get In Touch
Partway Through a DITA Migration?
We train documentation teams in DITA on their own content, coach them through the first releases, and deliver the output through the Content Portal. Tell us where your roadmap stands.