DITA 1.2: What's in It for Writers?

By Kristen James Eberlein | Senior Member

“After working on this release for (can it be?) almost three years, I am delighted that the baby has left the nest…“

OASIS approved DITA 1.2 on 1 December 2010. After working on this release for (can it be?) almost three years, I am delighted that the baby has left the nest, and I think that its new features offer a lot of potential for making technical communicators’ lives simpler. In particular, I think that the robust extensions to the conref (content reference) mechanism will save writers time and enable them to produce more personalized and thus meaningful content for their end users.

DITA's Reuse Mechanisms: Topics and Conrefss

Unless you've been playing ostrich and keeping your head buried in the sand, you've heard of DITA—the Darwin Information Typing Architecture—and heard its name linked with the terms reuse or single sourcing. In fact, when DITA was first approved as an OASIS standard in 2005, articles touted it as the “Holy Grail of reuse.” DITA's powerful capacity for reuse is driven by two key aspects of the architecture: Its use of small, granular information units (topics) and its use of an elegant transclusion mechanism (conref).

Figure 1. Cover Pages article about DITA

The value of topics is easy to understand. If your content is broken down into small building blocks, it becomes far simpler to reuse them in different deliverables or output formats than if the information is stored in chapters or appendixes. What a conref is and what it does is slightly more abstruse.

The conref mechanism enables authors to define pieces of content in one place and then pull them into another place. These reusable entities can be entire topics, a paragraph, a definition list, an entry in a definition list, an index term—in fact, any element that holds content. While many writing teams initially use conrefs only for traditional boilerplate material, such as warnings, cautions, notices, and trademarks, many teams quickly explore other ways in which using conrefs can help impose greater editorial style and consistency on the documentation. Want to ensure that information about performing an action in a software application is always presented to the reader in the same way? Use a conref to pull in a element. Do you have APIs or commands that use the same parameters over and over again? Use a conref to ensure that the parameter always is documented in the same, identical way. Or are you creating a collection of new topics and there currently is not consensus on what the section titles should be? Use conrefs for all the section titles, and when your editors makes their decision, all the titles in the individual topics can be changed simply by altering the titles stored in the reuse file. (If each of 450 topics has six section titles, this is 2,700 titles that otherwise would have to be individually modified; this is no easy task if topics are stored in a content management system and must be individually modified.)

DITA 1.2 Extensions to the Conref Mechanism: Conref Range and Conref Push

DITA 1.2 contains several new extensions to the conref mechanism. The two that I think will be of most use to writers are conref range and conref push.

The new conref range feature eliminates one of the tedious tasks writers documenting software often faced when using DITA 1.1—the need to individually specify each element that they wanted pulled into the topic. If you wanted to conref steps from a task topic, for example, and your users need to perform the same five steps over and over again, you were stuck with conref'ing individual steps one by one, over and over again.

Figure 2. Conref'ing adjacent elements in DITA 1.1

Now with DITA 1.2, you can conref multiple contiguous elements into a topic. Simply specify a beginning and ending element—they must be of the same element type—and everything in between comes along for the ride.

Figure 3. Conref'ing adjacent elements in DITA 1.2

Note that the in-between content does not need to be enclosed in the same elements as the beginning and ending elements. You could conref a range of elements that begins and ends with paragraphs, for example, but which contains many other elements inside the range: tables, lists, images, figures, and much more.

The new conref push feature enables writers to push additional content into an existing topic. The new content can be placed before, after, or in place of existing content. The new content and the existing content, of course, must be of the same element type.

Use Cases for Conref Push

Consider the following powerful use cases for the conref push mechanism:

Adding content to auto-generated DITA topics. A software company generates hundreds of API reference topics every night, using an automated process that builds the topics from the product source code. The company's technical writers want to add some additional content to the files, to make them more useful for end readers, but they know that their edits would be overwritten every evening. The conref push mechanism provides a solution. The writers draft the content to be pushed into the API reference topics. Every night the topics are regenerated, and every night the human-authored text is pushed into the topics.
Providing a temporary fix for a documentation issue. A printer manufacturer discovers that Microsoft has changed a configuration setting in Windows; this change invalidates the manufacturer's instructions for installing a printer driver. They need to issue a patch to the installation topic on their website. Since the company will have an updated driver in a matter of days, they do not want to change the source for the installation topic. Using the conref push mechanism, they can create a temporary fix that will be simple to remove once the printer driver is updated.
Reusing topics between documentation teams. A large company uses DITA for their technical documentation. One product, an integrated development environment (IDE), is the basis for another software product. The installation process for the two applications is almost (but not quite) identical; there is one extra window for the second product. The IDE is released before all the development work on the second product is completed. The technical writers for the second product then use conref push to add the content for the additional installation step to the content authored for the first product.
Modifying third-party documentation. A hardware company provides their customers with a documentation package that includes some third-party documentation. They need to add a warning to the third-party documentation, but for contractual reasons, they do not want to ask the third party to make the change. Since all the documentation is sourced in DITA, the hardware company can use conref push to add the warning.

Using Conref Push to Customize Documentation

Right now, what I am most excited about is using conref push to produce customized documentation. One of my company's products—SDL Trisoft—is a component content management (CCM) system that is customized extensively to meet the particular needs of each purchasing company. I am in the midst of redesigning the product's documentation so that companies that purchase SDL Trisoft can use conref push to replace sections of the documentation that refer to the out-of-the-box configuration. If our DITA source files are well architected and modular, other companies will easily be able to use them to render documentation that is customized for their specific needs. Since our primary documentation deliverable will be an information portal that dynamically renders DITA maps and topics on demand (using SDL LiveContent), we'll provide the DITA source files as an essential part of our documentation. If we provide hooks (DITA @id attributes with values) in the correct places, our customer won't even have to modify a single character in our source files but will be able to use them as the basis for their own unique documentation. What a winning proposition! In exchange, we hope that our customers will continue to be forthcoming in providing us with feedback about how we can provide them with the best and most useful documentation possible.

Of course, it will take a little time before authoring tools and CCM systems catch up with the new DITA 1.2 standard. When they do, I think technical communicators will rapidly make use of the convenience of conref range and the explosive power of conref push. I very much look forward to seeing how our community uses these new DITA 1.2 features.

DITA 1.2: What’s in It for Writers?

DITA's Reuse Mechanisms: Topics and Conrefss

DITA 1.2 Extensions to the Conref Mechanism: Conref Range and Conref Push

Use Cases for Conref Push

Using Conref Push to Customize Documentation

Further Reading