If you’re planning on using DITA—it often entails more than simply setting up an infrastructure and training writers.
By Lou Kummerer, Senior Member
DITA offers a powerful range of capabilities, but those capabilities come at the cost of higher document complexity, greater resource demands, and longer production cycles. DITA’s increased costs can be circumvented by simply not implementing some of its more challenging features. However, doing so seriously diminishes the true value of using DITA.
IBM originally proposed Darwin Information Typing Architecture (DITA) as a structured documentation model in the early 2000s. DITA has since become an industry-wide standard for structured content, especially among companies with high-volume documentation demands. Large corporations invest millions of dollars in DITA implementations, hoping to reap the benefits of a structured approach to content development.
However, DITA is complex and the toolsets that support it frequently have steep learning curves. Taking advantage of DITA’s full range of capabilities incurs a cost in terms of time, resources, and complexity.
If you or your technical publications group are new to the DITA world, you may be tempted to avoid DITA’s additional overhead by skipping some of its more challenging features. By doing so, you reduce DITA and its accompanying toolset to little more than an expensive authoring tool with a steep learning curve.
Four DITA features particularly prone to underuse are information typing, conditionalized content, re-use and variables.
Information Typing
Information typing requires that content be segregated according to its function. Each information type has a unique set of restrictions and formatting requirements. For instance, a section defining acronyms is formatted and organized differently from a section containing a procedure. Each information type is created in a separate module isolated from other information types. More importantly, the content of one information type is never comingled with the content of another type.
Information typing forces content into sections that have a clear, unadulterated purpose. It allows users to quickly find what they are looking for without having to slosh through a muddle of irrelevant information.
Information typing is encoded in DITA’s genes. The DITA specification organizes basic information types into Concept, Task, and Reference topics, each of which defines XML elements unique to that type. For example, the DITA XML Steps element, which defines steps in a procedure, is unique to the Task topic.
However, information typing demands that you carefully analyze your writing projects to ensure that all content is segregated into the appropriate information types. Furthermore, organizing content into rigidly defined information types increases the complexity of the document.
Because DITA also provides a generic DITA topic module, you may be tempted to simplify your DITA documents by forcing all content into the generic topic rather than using separate topics for each information type.
The skilled writers in your group might still be able to impose a fuzzy version of information typing within each generic topic module. However, the output across several documents will likely be inconsistent. Moreover, new writers who aren’t properly trained in information typing may revert to a more haphazard style where different information types are randomly intermixed, sometimes within the same paragraph.
Conditionalized Content
Conditionalization allows a single document to include mutually exclusive text variations, each aimed at a separate target audience. When the appropriate target audience is selected, only the text relevant to that group appears in the document. For example, documentation for a product marketed in both the U.S. and Europe may have measurements conditionalized so that when Europe is selected, all measurements in the document appear in metric format.
Most high-end authoring tools support some form of conditionalization, but few of them offer the same variety and flexibility that DITA provides. In DITA, conditionalization can be applied to virtually any part of the document, including phrases, graphics, even entire sections.
Conditionalization provides an efficient means of documenting products that have multiple permutations, each with only minor differences, such as an embedded controller chip where the only product variation is the amount of onboard RAM. For such products, conditionalization eliminates the need for creating a separate document for each of the permutations or for creating a single document that includes information on all other permutations when only one permutation is relevant to the user.
However, conditionalization can quickly become unwieldy, especially when multiple factors are involved—for example, a DRAM device available in 1.5GHz and 2.0GHz versions, each of which offers 8GB, 16GB, or 32GB of RAM with either a 1.9-volt or 3.3-volt power requirement. Correctly coding all these permutations is challenging. Trying to unravel them when new material is added to an existing document can be even more challenging. In addition, creating specialized profiles and setting up their associated definition files can be daunting, especially for inexperienced DITA users.
Faced with the difficulties in implementing DITA conditionalization, your first instinct might be to revert to a less technically demanding solution. Doing so may simplify the editing process, but it doesn’t eliminate the complexity. It only diverts it to another arena. Each variation must still be documented somehow.
If you create separate documents, each dedicated to a single permutation, the majority of the material in each of those documents will be common to all permutations. Changes to the common material will now have to be replicated in each of the separate documents. Tracking changes across each of the separate documents can easily become unmanageable.
On the other hand, if you force all the permutation material into a single document, you’ve passed the complexity onto your users. They must now forage through layers of irrelevant text to find the information specific to their needs.
Documenting products with multiple permutations is inherently complex. You can’t eliminate the complexity. You can only select the most practical method of dealing with it. While DITA’s conditionalization feature incurs an upfront editing cost, it is a less problematic long-term solution. It is also the most beneficial solution for your users, something that should be foremost in the mind of every technical writer.
Reuse
Reuse entails the ability to create a topic once and use the topic without further modifications in multiple documents. A structured document is a collection of individual topics, each created and stored as a separate file. The document’s organization is controlled by a map file. The map contains links to the physical location of the topic files to be included in the document. The document is then generated by executing its map file.
A single topic module can be reused in multiple documents by linking the module into each document’s map file. Changes to the module will automatically appear the next time the relevant documents’ map files are executed.
DITA is structured by nature, requiring that individual topics be rendered as separate XML files that are subsequently linked into an XML map. Furthermore, taking advantage of reuse opportunities in DITA is straightforward in a technical sense. Unlike more complex features such as conditionalization, reuse doesn’t involve complex editing processes nor does it require in-depth technical skills. Nonetheless, this powerful feature often falls by the wayside for reasons that are outside the scope of DITA or its toolset.
Reuse can only be implemented effectively if each writer knows in advance which sections of a new document have already been created elsewhere. If your technical publications group assigns writers to develop entire documents independently (commonly referred to as “working in silos”), opportunities for reuse are lost because writers lack visibility into where sharing sections with other documents might be possible.
Variables
Many technical documents remain in use for extended periods before undergoing a revision. These documents frequently contain certain types of generic references that are subject to change without notification. For instance, a document may contain a URL that points to a customer support website where product manuals can be downloaded. If the website is reorganized and the downloadable document links are moved to a different page, all those URL references become invalid.
DITA variables provide a solution to this dilemma. Variables allow text to be defined in a single location and subsequently referenced indirectly in multiple locations. The actual value of the variable (in the example above, the URL for the downloadable manuals page) is resolved only when the document referencing the variable is generated. Thus, the value of the variable can be updated in a single location and will automatically be included in all documents when their map file is next executed.
Using DITA variables requires establishing a linkage between the location of the variable definition, the variable references in each of the topic modules, and the maps for each of the affected documents. Creating and validating those links can be time-consuming and occasionally frustrating. Furthermore, someone must be designated as the point of contact for updating the variables when a value changes. Managing the updating process adds another layer of administrative overhead to your group.
However, your users have a right to expect that the documentation you give them is accurate and up-to-date. DITA variables provide a means of assuring that all references in those documents remain current across each document’s lifecycle.
Conclusion
If you or your group are planning on using DITA—or if you’re using DITA now in a limited fashion—be aware that fully utilizing DITA’s powerful capabilities entails more than simply setting up the DITA infrastructure and training writers to create XML modules. You must also consider how DITA will affect the way you produce documentation and the way you train your writers.
To begin with, you must be prepared to re-center your production processes around a preliminary analysis phase. New projects coming into the department must be thoroughly examined up front to determine how the proposed documentation should be information-typed, where there are opportunities for reuse, and where variables and conditionalization may come into play. Work is then assigned to writers based on that analysis.
In addition, writers must be trained in more than the basic mechanics of creating DITA modules. Every writer in your group should have a firm understanding of structured documentation, what its benefits are, and how it should be implemented.
Changing your organization to take full advantage of DITA invariably requires the addition of time and resources to the document production cycle—something that management is generally loathe to do. Your biggest DITA implementation challenge may be convincing your organization to accept the increased overhead as an integral part of DITA’s cost. When time and headcount are at a premium, that can be a formidable task. But it’s a task that must be undertaken. Otherwise, you risk using DITA without really using DITA.
Lou Kummerer is a technical writer working and living in the metropolitan Phoenix area. He has extensive experience writing for the semiconductor industry and is also a confirmed DITA advocate. Lou is an STC Senior Member and current president of the Arizona chapter of the STC.
