Where I Stand on DITA


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.

Adobe RobohelpMadcap Flare

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

20 thoughts on “Where I Stand on DITA

  1. Amy Morby

    It’s definitely time to switch to DITA. I work with DITA daily at New Dawn Technologies, and we absolutely LOVE it. It’s so convenient to be able to change one for an entire manual than to manually go through and change each reference on a billion different pages.

    There are even XML editors that allow you to preview the output before you actually build it in the cmd window. I’ve been using DITA for 6 months now, and honestly, I would never go back to not using it. It’s just so easy. I’ve watched three people go through the learning process with it, and they’ve all picked it up in as little as two weeks. I’m a huge fan, and I think all technical writers should be too.

    1. Mike H

      Regarding reuse, how is the DITA model different or better than what FrameMaker provides? FrameMaker books allow for common source and content sharing and text insets work the same as DITA chunks for reuse.

      How is authoring DITA content in an XML editor easier than authoring content in FrameMaker?

  2. Amy Morby

    it should say “conref” up there…..”It’s so convenient to change one conref for an entire manual…” Sorry.

  3. Tom

    @ Ellis, thanks for the catch about the typo — I fixed it.

    @ David, I keep meaning to check out the solution you have with DITA. I will check it out more thoroughly as I explore options.

    @ Amy, I’m glad to hear your enthusiasm for DITA. Is there any way I could check out some of the help files you created with DITA? Also, what authoring editor are you using? And would you be interested in writing a guest post for my blog about your experience adopting DITA?

  4. Jefferson McClure

    Good insights, Tom. We’ve just started a combination CMS and DITA project (which, luckily, is being funded by the customer training department rather than our tech pubs team). In addition to the chunking benefits that you mention, I’m very psyched about the imposed standards that we’ll be implementing. Modern technical communication just has no place for personality.

    I’ve also been thinking a lot about the convergence of DITA and Web 2.0 trends. There has been some recent work to somehow fuse together wikis and DITA (which, by definition, seems akin to moving the North Pole to the equator). But I think, as technical communicators, we can devise ways to overlay a seemingly tight hierarchical structure on to top of the chaos of wiki content. Our future, not really so different from the past or present, will lie in our ability to bring forth order out of the sound and the fury.

  5. Gordon

    As I’ve mentioned on my blog, DITA is an excellent methodology but the tooling side is still lacking. The investment required to get a DITA solution up and running is prohibitive and it’s only recently that that has started to shift.

    I’m interested in hearing your opinion on this though Tom, my take is that, for a team of writers, you really need a developer (certainly a developer-minded tech writer) at your disposal to get a DITA solution working, and even then it’s a clunky, not very friendly place to work within.

    That said, Author-it just announced 5.2 of their product which, apparently, allows you to author in DITA (at the moment we are on 5.1 and using DITA to model our content, although we aren’t actually using DITA XML).

    I do think DITA is an excellent idea, it just awaits an equally elegant solution to make it truly viable in the market.


  6. Ted

    Tom, I’d love to know more about this DITA-to-Wordpress importer you mention, but I can’t seem to Google up anything about it, even on Mike Little’s own site. Where does that reference come from? If I could get my hands on a tool like that it would make my week.

  7. Tom

    Jefferson, I liked your comment about the need to impose order on chaos.

    Gordon, I didn’t know Authorit allowed DITA authoring. Cool.

    Ted, As soon as Mike gets back to me about that importer, I’ll definitely write a post about it and, if possible, make it available on my blog.

  8. Joe (Utah)

    I’m still not convinced that DITA is the final word on this subject. True, DITA is an XML standard that is gaining some traction.

    My concern is that several of the companies/applications touting the standard don’t seem understand the reasoning behind the standard (I have e-mail communications with product evangelist to prove it).

    Alternatively, many of the companies that have not adopted the standard seem to better understand the logic behind information/content management (the paradox alluded to by Jefferson McClure).

    However, I don’t agree with the “North Pole/Equator” statement. DITA and many Web 2.0 technologies are built with the idea/goal of extensibility.

    So my advice is this: extensibility is what is important. If you use an application that let’s you export into XML, you will be fine regardless of where the industry goes.

    Just a small side note:

    I have a good friend who owns a company that is pioneering some pretty cool technology. His company built an application that reads any document file; and then, on-the-fly, converts the file into usable XML content.

    What’s neat is that the converted file always conforms to the organizational standards regardless the style sheet (or lack thereof) used by the user. And a user can continue to modify the file using the tool of their choice… which when saved is again converted back to XML.

    1. Mike H

      Exactly. DITA keeps coming up as the answer to all of our problems, but the concept isn’t new. Applying structure to content was introduced decades ago, DITA simply provides an XML-based topic-oriented approach. Reuse is simply defining content one and referencing it in multiple outputs, something FrameMaker has achieved for many years now.

  9. Tom


    Thanks for your comment. Can you point me to the website of your friend building an application that reads any document file and converts it on the fly to usable content? Sounds interesting.

    Re the point about DITA not mattering as much as XML, I agree. I just finished talking with an enterprise architect for an XML solution involving Mark Logic where I work. He said the content could even be in .docx format, as long as it was XML. The trick, though, is rendering the XML content into the variety of outputs. If you don’t use DITA and don’t rely on the DITA Toolkit to transform the XML into these published formats, then don’t you have to rely on some kind of custom XSLT-FO solution? Is that what your friend is building?

  10. adspediaRO


    I am from Romania working as a Technical Writer and recently heard of DITA and came to this website. Is there a specific software or tool that is to be used for DITA conformity? I would like to test it

  11. Pingback: DITA Where I Stand on the Darwin Information Typing | Wood TV Stand

  12. Pingback: DITA Where I Stand on the Darwin Information Typing | home lighting

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>