Darwin Information Typing Architecture (DITA): An Introduction to Editors

June 25, 2008
The speaker was Scott Prentice
Notes were written by Karen Asbelle and Scott Prentice

Have your clients asked you to work with DITA XML files?
Maybe you've worked with single-source print or online content destined for multi-media output ( for example, a reference publication that includes certain topics, and a companion guide using that plus other content.) Or, maybe you've needed to edit documentation notes that are used repeatedly in different situations, and it's your job to ensure that any time a source note changes, all references to it also change. All this can be done more easily with DITA.

What do you need to know to determine whether DITA would be useful in a particular project?

Let's assume you are involved in defining how the content will be used. Can it be separated into chunks? Can you boil it down into essential parts that can be labeled and linked? The effective editor should know as much as possible about the subject to guide and monitor the writing and ensure it is concise. This is because the content may not be read sequentially. In fact, it's likely that users will click on a link or use a search function to arrive at different parts of the document to obtain particular information. DITA simply formalizes this concept at the authoring level.

DITA programmer Scott Prentice discussed the basics to help editors determine whether DITA is something we want to add to our skill set.

DITA (Darwin Information Typing Architecture) is an XML format that supports topic-based (modular) organization of content, and promotes its efficient reuse. Developed by IBM and released into the open source community in 2004, DITA has been getting a lot of attention. XML is a markup language for documents that contain structured information. (All useful documents are structured in some way). Instead of tagging portions of a document with style indicators, XML tags indicate purpose or use. XML separates content from formatting, allowing you to define the structure (hierarchy and order) that all elements in the document are required to follow. XML files contain the content; the formatting is applied by other means, such as HTML and CSS.

Because DITA is an XML format, it can be written in any XML editor. However, due to DITA's special reuse constructs, it works best to use an editor that is specially designed for DITA authoring. There are a number of editors that support DITA authoring: popular ones are XMetaL, Arbortext, and FrameMaker. An advantage to FrameMaker is its built-in support for high-quality PDF output.

Structured authoring tools programmatically enforce the structure, which means that resulting documents are more consistent and follow predefined hierarchies. Structured authoring can automatically adapt to authoring changes by renumbering elements as needed, when their positions in a document change. Authors and editors can spend less time worrying about formatting and layout, which allows them to focus on the content.

With modular or topic-oriented authoring, content is split into discrete, stand-alone units of information called "topics." Writing in a modular way helps writers better organize, construct, and write documentation. Modular documentation makes information easier for users to find, follow, and understand. Chunking categorizes information into logical, independent topics based on content type, such as concept, task, or reference. "Labeling" should ensure that topic titles are unique, clear, accurate, and meaningful, with each topic type having its own specific heading syntax. "Linking" connects topics to other related or relevant topics so that users can easily find the info they need.

DITA supports efficient content reuse with two unique constructs: topic maps and content references. Topic maps ("DITA maps") let you arrange DITA topic files into hierarchies of components and deliverables, much like a table of contents; these maps can be treated like a file system. Content references ("conrefs") let you reference other elements at any level of the document's hierarchy, and reuse that content in other files.

The concept of specialization allows you to create new elements and content models based on the core elements. The notion of inheritance comes in here--hence the name "Darwin." DITA provides three specialized topic types: concept, task, and reference. DITA allows you to maintain different "containers" to safely store variations of a document. For example, the content for a brochure may require tweaking for a physician audience, a patient population, and a community of pharmacists, and thus each set, though similar, could be held separately, yet remain linked for later global updates.

With its open architecture, DITA frees you from integration problems with proprietary file formats and authoring tools that may vary within a company or community.

While you can create many files with DITA, it's recommended that you not name files with "readable" (word) titles because title names can change. Instead, Scott recommends using any sort of numeric file-naming convention that will never require you to update a file name when the document title changes.

Aside from DITA's sensible and easy-to-understand data model, a big reason for its high-adoption rate is the availability of a toolkit that provides transformation tools to generate various types of online output. Publishers who adopt a well-thought-out data model such as DITA can save months (if not years) of development time.

DITA Open Toolkit (DITA-OT), which is both free and open source, is a package of scripts and Java code for processing DITA XML files. The toolkit provides samples and documentation as well as XSL transformations that generate many types of online output, including HTML, CHM, JavaHelp, EclipseHelp, and PDF.

The only alternative to FrameMaker's PDF output is through XSL-FO, which, for reasonably complex output, is very expensive to develop and maintain; also, XSL-FO cannot match the quality of FrameMaker-generated PDF.

Scott Prentice is president of Leximation, Inc., providing tools and solutions for print and online publishing. He has worked in the technical publications field since 1991 as a technical writer but primarily as a tools developer, focusing on custom online Help and FrameMaker development. He has an ongoing interest in developing innovative ways to provide online user assistance that is actually used. Scott developed the core plug-in that became the DITA App Pack for FrameMaker 7.2, and was involved with development of DITA-FMx, an enhanced DITA plug-in for FrameMaker. Scott is the coordinator of the Silicon Valley DITA Interest Group, and programmer for the BAEF Web site. To get the latest version of DITA-FMx for FrameMaker 7.2 or 8.0, visit http://www.leximation.com/dita-fmx.