STC Houston - Dateline Houston - January/February 2006

Vol 45, Issue 3

January/February 2006

STC Houston - Dateline Houston - January/February 2006

Issue Home Page

Printer-friendly version

STC Houston - Dateline Houston - January/February 2006

To DITA or Not to DITA

Choosing Structure in an Unstructured World

by Dean Liscum, Information Developer, BMC Software, Inc.

At a recent STC-Houston presentation about DITA (Darwin Information Typing Architecture), a member of the audience asked, "Is it worthwhile to change the way we do everything?" The presenter responded with a technical writer's equivalent of "Duh!" and moved on to the next topic.

To the professional who makes her or his living from DITA, the answer is obvious. To the writer who's lucky to make a living (myself included), it isn't so obvious. This article is my attempt to justify a little structure in a chaotic but thriving universe information.

The Atomic View: Topics, Topics Everywhere

Information and its fraternal twin, documentation, are basic elements for survival. As with anything essential to existence, humans take information for granted and misunderstand it. Ask John Q. Public what information consists of, and you are as likely to hear "earth, wind, air, and water" as you are to hear "facts" or "things." The developers of DITA have concluded that the smallest relevant form of information is a topic. Everyone has been exposed to this view of information. It's the basis of the 5-paragraph essay we learned to write in elementary school. It's the unit of conveyance in our reference books and in our narratives. It's the unit of our linguistic transactions. Have a topicless conversation with someone other than an immediate family member and see how satifying it is.

DITA uses topics as the unit of its documentation architecture. I'm comfortable with topics, and although the information that I've developed is not divided into topics that are identified by a set of metadata, it easily could be with the help of an intern or two and some clear guidelines. So from a perspective that involves both creation and migration, DITA is worth it for me.

Isn't That Special

Of course topics differ not only in content but in type, tone, and significance. DITA accommodates these differences by providing four fundamental units by which to categorize information: topic, concept, reference, and task. These information types can cover everything from a warning to a prerequisite to a unique procedure in a larger process. Recognizing that these categories are rather basic, the DITA developers made DITA extensible. With respect to information types, extensibility means that you can take a fundamental unit and add (or extend) its defining criteria to narrow the scope of information to which it applies. With this feature, you can create derivatives or subtopics, such as a warning unit based on the fundamental unit concept. Or you can develop a troubleshooting procedure unit based on the task unit. A cursory analysis of document types (reference guide, error message manual, and user guide) and paragraph tags of my existing documentation quickly reveals the inherent information typing that already exists in my documents. For new documentation, these extended, derivative topics can serve as information templates that help you supply the required details. They remind writers what type of information is appropriate and ensure that each topic is uniformly and consistently addressed.

Again, I can envision my technical oeuvre transformed—with the help of a triumvirate of tireless interns and a little tyrannical oversight.

DITA also seems robust enough to handle both a loosely typed information set and a granularly typed set.

Some Assembly Required

So once the world, or rather the very limited world of my problem domain, has been documented in these bits, what do I do with it? My users don't want a pile of topics. They want help. They want structure. They want coherent user guides with which they can fill their briefcases and line their book shelves. Luckily, DITA enables construction of dynamic documents by using property-based processing. I create an outline and specify my delivery type, and a nifty DITA-enabled tool produces a help system or paper user guide or a Web- based decision tree.

Buy, Sell, or Puree

My conclusion is that DITA is a well-reasoned but complex structured methodology that is flexible enough to be customized, yet simple enough to be implemented with the aid of DITA-supporting authoring tool.

Is it work? Yes, but at today's intern prices, I think I can afford it. Is it worth it? I think so. The additional work of providing metadata for each topic isn't really additional work. I've already done the mental work of classifying the information. I just need to capture it in a form that is more persistent than my memory and one that can be readily accessed by a content management or documentation production tool that doesn't come shrinkwrapped with an ice pick and a bone saw.

DITA'd Out? No?

Find more information at http://www-128.ibm.com/developerworks/xml/library/x-dita1/.

Copyright © 2006 Houston Chapter, Society for Technical Communication
P.O. Box 42051, Houston, TX 77242-2051 | 713-706-3434
Disclaimer