DITA adoption -- seven years later

DITA has come a long way in the seven years since my last blog post. There are more resources, more and better tools, and livelier discussions on the DITA user groups. Yet Tony Self's What's Impeding DITA Adoption?, written just two years ago, still has currency. Why?

If you were reading my blog back in late 2006, you'd know that I was hoping to bring DITA into an unstructured FrameMaker shop with a lot of legacy documentation and a busy schedule. At the time, I thought the main impediment to DITA adoption would be lack of opportunity. My strategy was to write in DITA and convert to unstructured Frame, buying time to learn without disrupting our established processes. I thought this would allow some time for momentum to build around this promising new technology. I hoped we could assemble the necessary knowledge and tools gradually, and make a smooth transition a few years down the road.

In those seven years, we did assemble the knowledge and tools, and by 2011 we were well-positioned to start using DITA. The legacy documentation proved to be an immovable object, but a golden opportunity arrived in the form of a new product and a new way of doing things -- Agile, the perfect environment for incremental topic-based authoring. We began writing DITA topics as our way of participating in the sprints, and we gradually assembled maps, and we delivered updated WebHelp at the end of each sprint.

With this in place, I thought my work as chief DITA instigator and evangelist was done. But even with DITA established and delivering WebHelp every two weeks, three significant impediments remained.

The first was the technical mindset required to write in DITA. For the developers and programmers among us, the ones behind the specifications and the Open Toolkit, the cognitive load of XML elements, attributes, conrefs, maps, chunking, and so on may not seem onerous. But to the writers I worked with, bright people in their own fields, it produced fear and confusion. We had a good DITA editor: FrameMaker with the DITA-FMx plug-in. We offloaded output generation as much as possible, providing one-click results on demand using DITA2Go. We created guidance in PowerPoint, WebHelp, and Confluence, explaining which elements to use and when, how to work with reltables, and what you could safely ignore. But working with the DITA elements still inspired fear and confusion, and attributes seemed beyond comprehension. Some writers responded valiantly, but I could see them struggling. Others just tried to avoid DITA altogether.

The second impediment was more subtle, but in ways more devastating. It concerned the transition from the book model to the topic model. Learning to write in topics takes time. The writers had no sense of an overall picture; they would frequently build an output just so they could orient themselves. I advised content planning as a remedy, but this requires a certain departmental culture that had never really taken hold, despite my lonely attempts to set an example over the years.

This impediment had a corollary in choppy writing. In some cases, as the writers tried to figure out topic-based authoring, they would produce topics consisting of a title, a shortdesc, and one step/cmd. We were delivering what Mark Baker calls "Frankenbooks," and in what I can only describe as a rarity for our profession, we got feedback from our users. That's how much they didn't like it. I proposed chunking as a partial remedy; see "fear and confusion" above.

The third impediment happened while no one was paying attention. The training department, an independent operation at another branch of the company, finally gave up on Microsoft Word and adopted FrameMaker -- not just for its long-document reliability, but for its condition support! They wanted to produce custom documents for a host of customers from a single source. As a technical specialist, I spent some time helping one of the trainers develop advanced condition expressions using FrameMaker's less than helpful environment. DITA would have been a better choice, at least to this extent. But licenses had been bought, training sessions attended, and working alliances formed with our own unstructured FrameMaker specialists, and no one was going to throw it all over for new tools and new ways of working. The embarrassment factor would have been too great.

So that's what impeded DITA at this particular shop: its complexity for non-programmers, its tendency to enourage fragmented content, and its marginalization by established software and practices. I'm sure some of you will have thoughts about how it could have gone better. I'm no longer there, and I'm now happily working with DITA and oXygen and carefully avoiding Frankenbook-style writing. Older but wiser, I thought I would share with you how the rollout went.