What Is DITA Conversion?

TechWhirl's DITA articles and resources are brought to you by easyDITA. Learn more about their product & sign-up for a free trial at easydita.com.

image source: listal.comAs you explore the benefits and challenges of using Darwin Information Typing Architecture (DITA) to manage your technical content, you’ll find several business terms bandied about that sound synonymous but aren’t. DITA Conversion should be not confused with DITA Adoption. The two are related but distinct.

DITA Conversion refers to the processes that take your content pre-DITA and apply DITA tags to it until it is fully structured and valid DITA markup.

DITA Adoption, on the other hand, is the entire process of moving from an unstructured writing environment to a structured, DITA environment. DITA Adoption includes DITA conversion as one of its steps as well as tool selection, content strategy, planning, filling roles, implementing reuse, setting up publishing, and a lot more.

While DITA conversion is part of the larger DITA adoption process, it requires significant forethought, planning, and resources on its own. So we’ve prepared this overview to DITA conversion to help you start evaluating what it will take to convert your content to DITA.

A Tongue-in-cheek Example of DITA Conversion

Pre-conversion

Taking Over the World

You may want to take over the world if you have determined the world cannot prosper without you.

Prerequisites: Delusions of grandeur or impressive skillsets.

1. Plan the best way to take over the world.

2. Assemble the people and tools you have determined you need.

3. Work with your team to slowly establish dominance.

You should consider a benevolent dictatorship if you want to remain in power for any length of time.

4. Continue adapting your plan as circumstances change and people react.

Result: You now have complete and total world domination.

Post-requisite: Take over the galaxy.

Post-conversion

Viewed with tags on:

structure_example_tags

The same thing, but viewed as code:

structure_example_code

Of course neither of these is what your end users will see. As part of your DITA adoption (rather than conversion), you will transform XML to outputs like PDF, HTML, ePub, and whatever else you need.

During conversion, you take your content in Word or FrameMaker (or whatever unstructured format you have it in) and put the right DITA tags around the right content. After conversion, your authors can begin updating and reusing content, and developing the publishing mechanism you need to deliver the outputs.

Deeper Dive: Best Practices

Of course, DITA conversion is really more complicated than simply putting tags around existing content. Typically, 90% of pre-DITA content needs to be re-written from its book- or document-based format to DITA’s topic-based structure. Specifically, content usually needs to be split into task, concept, and reference. Often, pre-DITA content mixes information types together, which makes it less consumable and less usable for the end user. So content cleanup is imperative.

The process of cleaning up content prior to conversion has three major benefits:

  • It increases the quality of your content.
  • It forces you to learn the best practices of topic-based writing and the basics of DITA before you even have XML to work with (learn to walk before you run).
  • It allows for a much faster, smoother conversion with higher quality results.

Keep in mind that cleaning up content after conversion is an onerous and time-consuming task and takes on average three times longer to perform. It is not recommended. Instead you should plan for content cleanup prior to conversion, and performing a content audit can help streamline that process tremendously.

Conversion Methods

You could choose among three main conversion approaches, using different types of resources:

  • In-house
  • Conversion companies
  • Consultants

All three of these use some method of mapping styles to elements, so the better your application of formats and styles to your content, the cleaner the conversion will be.

One frequently used method by both in-house resources and consultants is FrameMaker conversion tables (applicable even if your source is not in FrameMaker), which allow you to programmatically apply structure to many files at once. FrameMaker plugins (FrameSLT and FrameScript, used in combination) further allow you to script a series of actions that would take you days to perform, such as transferring FrameMaker conditions to DITA attribute values.

Scripting these tasks reduces the time spent converting content to hours or minutes rather than days. Usually, you’ll need to run a series of scripts to perform the variety of actions you need in the order you need them. You can create these scripts yourself or hire a consultant to build them; they do not come with the purchase of either FrameMaker or its available plugins.

An alternate method for conversion is to use hybrid solution such as Stilo’s Migrate, which lets you perform your own conversion at your own pace using their tool, accessed through a web interface. One advantage to a cloud-based hybrid solution such as Migrate, is that you pay as you go and are in charge of your own conversion, using their tool to map your styles to DITA elements and attributes. Stilo offers support and full-service options for DITA conversion.

Your success in conquering the world of DITA relies in part on understanding how you should identify, clean up, and convert existing content into flexible, reusable, topic-based content.

Resources:

This article and all TechWhirl articles on DITA are brought to you by easyDITA, the all-in-one DITA authoring and content management solution at easydita.com.

Jacquie Samuels

Jacquie Samuels is the owner of Writing Wise. She endeavors to help everyone create documentation that is stronger, faster, and smarter. You can connect with Jacquie through her Google Plus page.

Read more articles from Jacquie Samuels Twitter