DITA migration strategies

Migrating to DITA means more than just adding element tags. There are a few common holes in migration strategies that can prevent you from reaping all of the benefits of the converted DITA content. To avoid that mistake, make sure you have a plan in place for:

• Identifying and migrating reused content
• Managing links
• Processing images

These should be important factors when migrating your content to DITA, and they will require new workflows and changes in the way you handle the relationships in your content.

Identifying and migrating reused content

During migration, you will be separating long documents in PDF or Word format into smaller components or topics. The ownership of content within documents will vary if you are efficiently reusing componentized content. The same person may not be the author for all topics within a document. Instead, there will be shared topics that are common to more than one document. For example, introductory information may be common to all documents, or a specific set of documents is written and approved once and then referenced in each of the other documents.

When you evaluate which content to migrate, consider how to migrate that reusable content. You could migrate the entirety of each document and restructure for reuse later, but ideally you identify reuse before migration, and convert the Introductory Info topic only once.

After you migrate, the document is made up of many topics. It will likely be authored by more than one person, and when the document is approved or rejected, multiple people will have to revise the individual topics that comprise the document.

Migrating references

Similarly, you will want to address the way you handle links or references to other documents or document sections. In unstructured content, those references may be embedded in the body text of a document. When you migrate to structure, consider other methods for linking content. A link within the content body is difficult for both authors and readers to manage. For authors, it can be challenging to locate links within the text to edit them when the content or the referenced material changes. For readers, a link in the middle of the text can be distracting.
When you prepare to migrate content, think about the links as separate from the body text whenever possible. This may involve some rewriting before or after you convert the content. A list of related topics is much more manageable than links within the text.

Again, you will have to consider how to manage link approvals. Referenced documents or topics may change or become obsolete as the content changes. (DITA relationship tables provide some features that help make this work less time-consuming.)

Processing images

Images present several migration challenges. First, make sure that your images use a file type supporting in your new DITA publishing workflow. If they do not, you’ll need to convert your images to a new format.

Transitioning your images to use in DITA content is more difficult if they contain text, such as captions or labels. Best practice is to keep the text separate from the images. You can then create an image legend in DITA that accompanies your image. This approach lets you use one version of the image in various topics or languages.

If you have images with text, you will need to recreate that text as DITA content if you hope to reuse or translate it or resign to expensive image processing in localization.

 
 
Migration to structure can be a difficult undertaking, but if you can anticipate how content relationships and reuse will change, it will make the post-migration transition much smoother for everyone.
If you need help developing a DITA migration strategy, contact us