"The problem is that most software will assume a "pure" out of the box DocBook implementation, and the reality borne through my experience, is that there are very few "pure" DocBook implementations out there."

The problem is that most software will assume a "pure" out of the box DocBook implementation, and the reality borne through my experience, is that there are very few "pure" DocBook implementations out there. Most DocBook users have made some customized tweaks and additions to the base DTD. If you are one of them, an out-of-the-box conversion tool will likely not work out of the box and you should evaluate how much work it will need for the product to work well enough that you don't end up with lots of cleanup work. Cleanup work is often more expensive than doing the upfront work to avoid it.

"Understanding the degree of inconsistency in your document set will help you ensure that the conversion process or a tool you choose addresses them appropriately."

DocBook allows a fair degree of flexibility in its structure and since writing is creative in nature, many writers have used this flexibility to add creative touches to convey information to the user in the way they felt was best. However, while the intentions were noble, this approach often results in documents with inconsistent use of element structures - presenting difficulties for automated types of conversions. Understanding the degree of inconsistency in your document set will help you ensure that the conversion process or a tool you choose addresses them appropriately.

Topics are groupings of information that one would consider a reasonable module that could be repeated in other places if necessary. The next factors to evaluate are the various topic types in your document set as they would apply to DITA: task, concept and reference. Since DocBook does not distinguish its components based on these types, the content you want outputted as a task may have identical source tagging to the content you want outputted as a concept.

If the entire document consists of only the same type of topics (like concept) or 80%-90% of the same topic type, then out of the box conversion script may still be a good option. Otherwise consider that you would need a way to impart the information on the various topic types to minimize after-the-fact rework.

Technical documentation often has multiple levels of heading hierarchy, and the headings might mean different levels of granularity in different parts of the documents, and since most documents were authored without a modularized DITA idea of stand alone topics, new topics will vary based on the actual content. So the "why don't you just…" rules like each <block> becoming a new DITA topic will likely not work that well. There's more sophistication needed to make this work well

"If you however find that granularity was maintained at a fairly consistent level, or if you choose to pre-edit your documents to define the same level of hierarchy for chunking into DITA topics, then an out-of-the-box conversion script may still be a good option."

If you however find that granularity was maintained at a fairly consistent level, or if you choose to pre-edit your documents to define the same level of hierarchy for chunking into DITA topics, then an out-of-the-box conversion script may still be a good option. Otherwise, without some pre-planning, you might end up with significant after-the-fact cleanup.

The true benefits of DITA come from features and tagging that don't exist in your source documents. Adding those tags and features is what we mean here by data enrichment. It's best to truly understand what kinds of added (or enriched) tags you want from your conversion and to find a solution that will support those new requirements. DITA has a large number of specialized tags like User Interface Element to add additional levels of granularity. For example in your existing source data <uicontrol> may be done just as bolded text, making it difficult for software to distinguish when <emphasis role="bold"> should be converted to a <b> tag and when it should be converted to <uicontrol>.

Another example is a use of conrefs to facilitate content re-use. If the variable that you'd like to re-use via conrefs are done as regular text, special conversion routines may need to be developed to add previously not available information. (NOTE: In most cases it's not a simple search/replace as phrases often appear as part of the bigger context that can be impacted by the conversion. For example, you want to replace "DCL" with a variable that will be defined as "Data Conversion Laboratory Inc.", but if your text contains this term in another context too, like Part No. 235-DCL-0001 then a simple search/replace type of action would introduce an error.

Understanding your data enrichment requirements prior to the conversion is an important checklist item to ensure that you've selected an effective conversion solution. Sometimes an automated script will not be able meet all these requirements

So if you are ready to consider converting your DocBook docs to DITA, make sure you thoroughly analyze your document set first, and get answers to some of these questions by asking yourself and asking your vendor. Doing this will take you a long way down the path of knowing if and how you can move to DITA and enjoy all the benefits it offers.

DCLNews Editorial
June 2008