Where I Stand on DITA

by Tom Johnson on Jan 23, 2009
categories: wordpress

DITA (Darwin Information Typing Architecture) is an XML standard in technical communication

For a blog about the latest trends in technical communication, I've been conspicuously silent about DITA, the XML standard for technical documentation that is rapidly becoming the norm in the industry. Tonight I realized that I need to examine more closely where I stand on DITA. Several events prompted this.

At my work we have a small authoring group that is tool independent. I use Flare, another colleague uses RoboHelp, another colleague has no need for a robust help authoring tool, another department uses UPK (Oracle's help authoring tool), and we don't really have a unified approach. Adobe just released its new Technical Communication Suite that includes the latest version of a package of tools. Flare continues to move forward, as does Author-it and Doc-to-Help. But I'm feeling a bit fatigued by these proprietary tools. Rather than choosing another tool, I would rather choose a standard format and let individuals choose their own tools to create documentation in that format.

The WordPress Docs mailing has also been heating up. Apparently WordPress has come to the realization that its Codex, a giant wiki that would kill all trees in the world if printed, does not satisfy the beginner's need for a basic "handbook."

WordPress' wiki has been, in my opinion, a fascinating project of community documentation. From what I understand, a previous wiki held WordPress documentation but was abandoned to create the Codex. Now the developers are considering transfering the core information from the Codex to a DocBook format, which they would maintain in a Subversion repository (SVN) so they can manage quality control and branching. If you want to see in to the heart of Web 2.0 and documentation, look closely at WordPress.  The Codex has grown beyond itself, become chaotic, redundant, outdated in parts, maze-like and unnavigable. Still, nuggets of essential information are spread throughout, making it indispensable. Maintained almost entirely by volunteers, the wiki proves to be a problematic format. It can't sustain long-term, massive amounts of information before people feel the need to start fresh again.

According to the WordPress leaders, the wiki's main problem is its inability to support branching. You can't easily separate documentation for version 2.2 from 2.3 to 2.4, 2.5, 2.6, and 2.7. On the wiki, it's all the same page.

Fed largely by user-generated content, wikis will inevitably contain stale information. For example, the long page I contributed to the WordPress Codex remains dated to version 2.5 or so, whenever I wrote it. (I'm not inspired to update it.) There's no ability to impose quality control, to have a systemic way of sorting and verifying and organizing updates, changes, and other modifications.

Most importantly, though, the wiki doesn't support flexibility of deliverables. There's one product, one massive mountain of information. Each user has to make his or her own path through it. In all the documentation I've delivered, the long manual -- the massive wad of information -- has always been met with disgruntled looks and resistance. Users want condensed, short chunks of information specific to their role and situation. They want information without inundation. This brings me to DITA.

DITA provides the ability to chunk information, to deliver selected topics in a variety of compilations and output to various formats. It allows the passing back and forth of this content among authors regardless of tools.

My hesitation with DITA has only been that it's too early to adopt. But I believe the turning point has come. There are, now, enough plugins, transforms, authoring editors, and other supporting technologies that writers can begin to use DITA successfully, without setting themselves too far back.

DITA has even made headway into WordPress. Mike Little says he has built "an importer which will take the XHTML generated by DITA and import it into WordPress as a
hierarchical set of pages." He  "even have a version for WPMU [WordPress Multi-User Edition] that supports populating each mu blog with separate areas of content."

I've kept my eye on DITA for the past two years, but I think it's finally time, at least for me, to look more seriously into adopting and implementing it.