We need a frank, open discussion about the problems with DITA adoption

My second post on this blog was Case study: DITA topic architecture, in which I described some problems I inherited (twice) with DITA topic architecture.

Thanks to Mark Baker, author of Every Page is Page One, the post was widely read. (He referenced it on his blog and also tweeted it.) The post got hundreds of page hits and generated several comments and a few emails. It also spawned a somewhat defensive thread on an OASIS forum.

I have a lot to say about DITA. I have been holding back because I was concerned that my new blog would be written off as a DITA-bashing forum. I have a lot of other, less controversial (or differently controversial) things to say, and I didn't want to turn off a whole section of the tech writing community even before anyone knew who I was. But it seems that despite my best intentions I have been branded an antiditastablishmentarian. :-) So here I go...

I think it's time that we have a frank and open discussion of the pro's and cons of DITA. For years now all discussion of DITA has been dominated by its proponents; we have heard plenty of arguments for why to adopt it. We need an open discussion not to bash DITA, but to uncover issues so that we can address them.

Here are just a few of the issues I want to address:

• Has DITA changed tech writing output? Is there a discernible style to docs created in DITA? If so, is this what we want - and how can we change it?
  
• How has DITA changed the work environment for writers? Do writers have less control over their content in DITA shops? What is the effect of that on quality?
  
• How has XML/CMS adoption affected the creative process for writers?
  
• What is the culture of DITA, and how widespread is it? Has the emphasis on monitoring writer's attitudes towards DITA changed the culture of tech writing?
  
• How much is DITA really costing companies, when you include the need for enhanced tools teams and information architects, CMSs, and more time spent by writers on non-writing activities?
  
• DITA proponents make claims about the cost of non-DITA solutions, such as that writers spend 30-50% of their time formatting. How true are these claims?
  
• Has the rise of DITA increased the influence of consultants on tech writing? How has the agenda of consultants (to attract business) changed our profession?
  

These issues are of immediate, practical interest to me. I lead a doc team that uses DITA. I have authored in XML for 12 years. I have been a judge in the international STC competition (that judges the highest scored winners of the local competitions) for over a decade, giving me a chance to see the trends in our profession.

To the DITA proponents, I want to say that there is more that unites us than divides us, and to let you know that my goal is always to eventually reach common ground. My other, much longer-running blog is largely about politics so I have experience with this approach. I hope some of you will stick around to duke it out so that we can reach some consensus.

My bottom line is: I think there are some things to be concerned about with the widespread adoption of DITA, and we can't fix them if we don't acknowledge them. Let's dive in and see where the discussion takes us.

Case study: DITA topic architecture

This post is part of a series of posts that question some of the claims made about the benefits of DITA adoption.

(Note: DITA uses the word "topic" to refer to a reusable module of content. Out in the rest of the world the word topic tends to refer to an HTML page or a section of a PDF. This may be seen as an infuriating oversight, but I suspect it's actually deliberate. For a while I tried replacing DITA "topic" with "reusable module of content" but I have given up and now just use the one word to mean multiple things.)

I started with DITA several years ago when I got a job in a large doc team that had been using DITA for a while. I inherited a few deliverables and was appalled at the way the content was broken up into concept, task and code sample topics. We optimized for HTML output and there were too many brief HTML pages that users had to click through. Even for a simple idea that could have been covered in one paragraph, these docs would have three topics. For example, a description of how to stop the server would have a concept, task and sample topic, each appearing on separate HTML pages.

My audience was developers. I did quite a lot of usability testing with them and found they were furious about the documentation. They hated having to click through multiple tiny pages. They hated the minimalism and choppiness. They described the docs as unfriendly, officious, insulting and unhelpful.