The Darwin Information Typing Architecture, or DITA, is an OASIS standard for creating and managing modular, reusable, XML-based content that can be published in a variety of formats. The architecture has been in production for twenty or so years, so most teams have already established whether or not DITA will work for them. Instead, they are more concerned with determining the cost of DITA, the constraints that the architecture places on authors, and the returns on investment.
The information typing model and why it constrains authors deliberately
The author’s types for document content are within three main groups of content, tasks for procedures, concepts for explanation of ideas, and reference information for simple lookup such as tables of parameters, error codes, or detailed specifications. DTDs and schemas are provided for each type of content, so for example, a step cannot be placed outside of a task and a table of parameters will have a specific place to put such information.
Restricting authors to a specific set of document types helps to prevent them from solving the same problems in different ways in different documents. The resulting content is then easy to process by subsequent systems, such as to render tasks with steps numbered in sequence and list items formatted as indented lists, for example.
Specialization as a controlled extension path
Specialization in DITA allows new element types to be defined as special cases of already existing ones. A troubleshooting type, for example, is a specialization of a task. Its processing in stylesheets remains unchanged since it is a task. The functionality of such new types is often not used enough by authors, and they therefore are only used to extend the range of already existing elements.
Topics, maps, and the separation that makes reuse possible
As content objects, DITA topics are most useful as standalone units of content that have value even outside the published book. A single topic can be reused in a variety of different contexts such as online help, training, and even other manuals. The hierarchy of the content and the sequence that content appears in is defined in another file, the map that defines the published content.
These topics can then be easily reused in an on-line help system or even in training materials. A single topic is a self-contained piece of content that can be published in any number of different ways, and teams new to this separation are better served by working through a plain explanation of what DITA is before they commit to a map structure. Changing a single topic will then update every map that references that topic at the next build.
Reuse granularity and where teams overreach
The DITA reuse features include topic reuse, metadata reuse, and content reuse. Each of these has its own level of overhead to get to full value.
- Topic level. Referenced from multiple maps. Cheapest to manage, highest return.
- Element level. Using conref or conkeyref to pull a warning, step, or table row from a library topic. Powerful, but creates dependencies that need governance.
- Key based. Indirect references resolved by the map, so product names, URLs, and links vary by output without editing the topic.
- Conditional. Filtering content at build time by audience, product, or platform using attributes.
One of the biggest mistakes implementations make with conditional processing is very deep and complex conditionalizing within a single topic. This very quickly makes the content very hard to read and to test, and topics with more than 2-3 dimensions of conditionalizing are usually better off as separate variant topics for different maps.
Publishing and the real cost distribution
DITA can be output to HTML5, PDF, EPUB, and a host of other document types using the DITA Open Toolkit. While there are many commercial products built on top of this that offer improved PDF generation, better editing environments, etc., the real work of setting up transformation to different output types is the customization of the transformations themselves, usually underestimated by the project plan.
| Phase | Main effort | Common underestimate |
| Information architecture | Defining types, metadata, map structure | Reuse rules that nobody documents |
| Content conversion | Migrating legacy source into valid topics | Cleanup of inconsistent legacy markup |
| Output customization | Stylesheets and PDF layout | Brand compliance on print output |
| Author enablement | Tooling, templates, training | Behavioral change away from page thinking |
Where the return shows up
Translation is typically the most cost-effective activity. As the same topics are reused in all deliverables, they need to be translated only once. Subsequent updates of content are only sent to the translators for the parts that have changed. Most projects that publish in more than four to five languages will have broken even within a few release cycles.
Deciding whether DITA fits
Yes, especially in the following situations, substantial content reuse across product(s) / deliverable(s), output to multiple formats from the same content, extremely high volume of content to be translated, and / or highly regulated content that requires structured content and the ability to track changes.
DITA is not suited for short-lived, primarily narrative content created by a single author in one language for distribution in a single format. While some segments of marketing content may be suitable for DITA, long forms of explanatory prose typically are not suited for topic-based composition.
- Audit existing content for actual duplication, not assumed duplication.
- Model the information types against real documents before buying tooling.
- Pilot one product line end to end, including publishing.
- Write the reuse and conditional governance rules before scaling.
For more practical detail on evaluating DITA for your specific situation, read the other Practical Guide, “A Guide to Choosing the Right XML Documentation Tool for DITA with CCSM”.
