Skip to main content

Migrating to DITA: convert or rewrite?

So you’ve decided to move your content to DITA. You want all the benefits of reuse and less expensive translation, and you’ve completed your content model. But now the question is, “What do we do with our existing content?”

    You have a few options:

  • You can write new content in DITA topics
  • You can convert the content yourself (usually a process of copying and pasting)
  • You can opt for an automated conversion (either by hiring a company to do it for you or developing your own conversion script)

Here are some questions to consider when making the decision.

Are you updating your content anyway?

Assess the current state of your content. If you plan to rewrite your content anyway (because of regularly scheduled updates, or perhaps a rewrite due to corporate changes), you may want to consider rewriting your content from scratch in DITA. Converting content that you will rewrite is a waste of resources.

Is your content suitable for topics?

DITA is topic-based, which means content can be used in multiple different places and contexts. If your content includes language such as “in chapter two” or “the image above,” any converted topics will be stuck in the same context and relative location. As you reuse that content in different places, “chapter two” may not exist and “the image above” may be three pages away. You will have to rewrite to use generic wording or use DITA references in their place.

In this case, you probably shouldn’t convert the content as-is, since you will need to rewrite it to fit a topic-based model.

How is your content formatted?

The format and implied structure of your content will determine how accurately your content can be converted.

For example, if your content is in Microsoft Word, and you have properly used paragraph and character styles, conversion may be fairly straightforward. But if your Word content hasn’t been formatted consistently or contains many formatting overrides, it may be difficult for conversion scripts to map your Word styles to DITA elements. The conversion will require a lot of clean-up afterward; your time may be better spent either reformatting before conversion or rewriting in DITA.

This logic extends to other formats, as well. If you have used a consistent implied structure, conversion will go more smoothly. Converting to DITA from another structured format like XML is especially straightforward.

How much content do you have?

If you have a small, manageable amount of content, using a conversion vendor may not be as cost-effective as rewriting.

If you have more content than you can reasonably convert yourself, consider a conversion vendor. But before you do, take a proper inventory of your content. You should prioritize conversion of your most important content and disregard any content that will not be reused or updated in the future.

How much time can you spare for conversion?

Rewriting content in DITA takes time, especially if you have writers who are inexperienced in using DITA.

Compare the cost of conversion services to the cost in time for your authors to rewrite the content themselves. If you cannot afford that much of your authors’ time, consider conversion.


An automated conversion process won’t be perfect; you will need to clean up the converted content. If you decide to rewrite your content in DITA, take comfort; this may be the last time you have to copy and paste.