We’re in DITA – now what?

Every year my talented friends at Scriptorium roll out a list of trends in content strategy and technical communication. This year’s list is thought-provoking as always: it contains some trends that are spot-on and some that I wasn’t expecting.

And one that’s flat-out brilliant: We’re in DITA – now what?


Muscle car (1969 Pontiac GTO – source: Wikimedia Commons, Gtoman)

During the webinar in which Scriptorium unveiled its trends for 2016, Gretyl Kinsey described a “second wave” of DITA adoption: a technical writing team has decided to switch to DITA  — either for the right reasons (as part of a carefully planned strategy) or for the wrong reasons (DITA sounded cool and trendy, or they had some extra money in the budget).

Having gone through the process of converting its content. the team is now finding that DITA isn’t a panacea. The 400-horsepower DITA muscle car is parked in the driveway. Now what do we do with it?

This is when some teams throw up their hands, or when buyer’s remorse sets in. The team, especially if they didn’t have sound reasons for switching to DITA in the first place, might want to return to its old tool set. Or, realizing that they’ve sunk a lot of treasure and talent into the DITA implementation, they’re inclined to limp along — driving the car but never getting out of second gear.

Even when the team made the switch for the right reasons, they might feel overwhelmed. All of the reasons for switching, like cost savings through reuse and greater efficiency in translation, didn’t just magically fall into place. A lot of work is still needed. In this situation, again, some teams content themselves with driving the car to the grocery store and back, never taking it out on the freeway.

What’s the right thing to do?

During the webinar, Scriptorium’s Alan Pringle and Bill Swallow emphasized that the team should remember the strategic reasons for switching. Keep the goals and requirements of the business in mind, and tailor your DITA implementation as needed.

In practice that might mean hiring someone to create specializations for meeting certain business requirements, or developing a workflow for translation.

Scriptorium’s Sarah O’Keefe added some more ideas in a subsequent blog post — for example, the team can deliver new output files, refine the reuse strategy, and integrate other content into the DITA infrastructure to encourage collaboration.

Those are all good ideas. But for each of them, “the team” actually means the manager or the information architect.

A lot of the time, it’s the rank-and-file writers who feel overwhelmed or adrift. They don’t know enough, or they don’t have enough confidence, to use the full horsepower of DITA.

So, in addition to what Gretyl, Alan, Bill, and Sarah recommended, here’s what I’d tell management to do for the team.

Provide follow-up training. The writers probably received training during the conversion process. But when it actually came time to work with their content they couldn’t remember everything they’d learned. Even when they did remember, the real content somehow wasn’t as easy to work with as the exercises they did in class.

Now would be a great time for follow-up training, and the training should be as hands-on, working with real content, as possible.

If nothing else, the training will help calm the writers down. If they feel adrift, it’ll give them a lifeline. It’ll reassure them that management wants them to master the tools and succeed.

Second, make sure the team members know, and are reminded of, the business reasons behind the switch. They’re not using DITA because it’s the cheaper alternative or because management wants to check off “best in class” on the Buzzword Bingo board. They’re using it to meet specific business objectives. When the writers understand and appreciate those objectives, they’re more willing to buy in. They’re also able to ask good questions, like “How can I do this so that my content fulfills the objectives?”

Have you been part of a writing team that was hit by the “second wave,” that had DITA but didn’t know what to do with it? What did you do? What advice would you give to a manager — or a rank-and-file writer — who was part of such a team?

Those are questions that need answers, as DITA adoption continues to increase. So please leave a comment and tell me what you think.

17 thoughts on “We’re in DITA – now what?

  1. Mark Baker

    Larry, I am feeling increasingly vindicated these days as more and more organizations are running into exactly the difficulties with DITA that I have been predicting for years. Even DITA advocates are increasingly acknowledging how difficult DITA is, though to a certain extent they are trying to deflect the blame onto the problem space itself.

    Elliott Kimber’s presentation Why is DITA so Hard (http://www.slideshare.net/drmacro/why-is-dita-so-hard) rightly points out that configuration management is hard, and claims that DITA is hard because configuraiton management is hard. But DITA is also hard because it exposes the difficulties of configuration management to authors rather than shielding them from it.

    You post on DITA keys (https://larrykunz.wordpress.com/2014/04/21/an-appeal-for-dita-keyref-useful-powerful-and-hardly-ever-used/) highlights this. Keys are a low-level database concept. Very powerful, to be sure. But also a concept that is alien to most authors and much more difficult to learn that it seems to people who are familiar with it (our old friend, the Curse of Knowledge).

    DITA’s whole model is fragile, difficult, and hard to audit, meaning that poorly managed and non-conformant data will inevitable accumulate and will be expensive to track down and control. Most organizations don’t have the skill to do it even if they have the resources.

    More and more I find myself talking to organizations who are finding themselves in exactly the messes that I predicted organizations would find themselves in. (Yes, there is doubtless some selection bias in that.)

    Naturally the first response to this will be to attempt to doubledown: more specialization, more training, more management cajoling. But eventually we have going to have to admit that the model is broken — that DITA is the first generation product, the one we had to build to throw away.

    And then we need to move on to developing systems that hide rather than reveal the configuration management issues, that let authors work in an environment that is natural to them.

    1. Larry Kunz Post author

      Thanks, Mark. I appreciate your thoughtful response. Given that DITA is hard (if Eliot Kimber says it’s hard, then it truly must be hard), then what’s the logical next step? Do we throw it out and start over, or is there another way forward?

      If DITA is the “first generation product,” what would the second generation product look like? Remember that it has to address the same requirements DITA was designed to address.

      Is the right answer to develop a second generation product, or to develop tools that make the DITA author’s job easier? For example, oXygen has wizards for creating conref and keyref statements. I know the wizards aren’t foolproof. But they do reduce complexity and make errors less likely.

      I hope that others (like the folks at Scriptorium) will jump in here and continue this conversation.

      1. Mark Baker

        Hi Larry,

        I think we have to learn the lessons and start over. That is what I am trying to do with the SPFE project (and I would very much welcome anyone who wants to help out with it). And SPFE is, of course, my vision of what the second generation product should look like.

        At the same time, I do have complete respect for those who want to keep building on DITA. I think we need development to proceed in multiple fronts because that way we learn far more more quickly and generate ideas that can cross pollinate. Sharp criticism is necessary between the different approaches, to keep each on their toes. But it should not be mistaken for disrespect.

        I don’t think a new approach necessarily has to address the exact same set of requirements as DITA. Part of my critique of DITA is that it seeks to address too many diverse requirements, and that contributes to it being so hard to use. There will be a diverse set of tools, and taken together they will have to address the full spectrum of needs. But their boundaries do not necessarily have to be drawn in exactly the same places as they are at present.

        In particular, I believe that we need to promote loose coupling in all our tool chains. With tightly coupled tool chains like every tool has now, you run into a fundamental conflict between the need for simple right-sized tools for different groups and the need for broader sharing and integration of content. Loose coupling, not the victory of one monolithic system is the right solution to this dilemma.

        Also, requirements are changing. Information consumption habits have changed radically and many organizations are still stuck trying to optimize the old paradigm rather than move to the new.

        Also again, the requirements that DITA is meeting are in many ways constrained by people’s imagination. We only tend to state requirements that we can imagine being met. The truly revolutionary products meet requirements we have not been able to articulate. DITA focusses on reuse-by-hand because that is a requirement people can imagine (though they fail to anticipate the configuration management headaches that will come with it). Other systems might come at the problem from a very different angle, providing very different sources of efficiency, resulting in very different requirements being written once the potential is understood.

        On tools, I think the pattern is clear. Tools can hide mechanical complexity, but they cannot hide conceptual complexity. It is clear, for instance, that developments in WYSIWYG XML editing has stalled out over the conceptual complexity of dealing with the abstract structures of elements and attributes, and the problem of how to show structure if you are hiding the tags. (http://everypageispageone.com/2016/01/28/why-does-xml-suck/) Similarly, keys are conceptually complex, not just mechanically complex.

        You can build a layer over the top of DITA’s conceptual complexity. I think some people are doing that in ad hoc ways. SPFE would allow you to do that in a consistent way. That may be the next step, especially for organizations that already have a DITA tool chain in place.

    2. Sarah O'Keefe (@sarahokeefe)

      Hi Mark. I have to disagree with your premise. We are not running into people who are bailing out of DITA. Instead, the people who contact us (again, selection bias!) are trying to figure out how to go from DITA-based version 1 to DITA-based version 2. They are looking for interesting ways to to manipulate content, integrate it with other systems, and generally move into a more sophisticated approach to content.

      Yes, DITA can be complex. But as Winston Churchill famously said, “It’s the worst option, except for all the others.”

      1. Mark Baker


        I think it is inevitable that when people hit difficulties with any system, some will turn aside, some will turn back, and some will forge ahead. Obviously when they do so they will turn to people who represent those different course. And of course, while not everyone will make the right choice, each of those choices may be right for some.

        As for “except for all the others”. Well, I don’t agree, obviously. But if you come to that conclusion, the next question is, do we just live with it or do we try to make something better? DITA would not exist if Michael and Don had not decided to try to make something better back in the day. There is no reason we should not keep trying to make something better, especially as experience makes us more aware of the weak points of DITA.

        We progress sometimes by evolution and sometimes by revolution. It is entirely appropriate that people should be working on both the evolutionary and revolutionary fronts, until it becomes clear that the evolution has stagnated or the revolution has won. And then we start over.

        Because the problem is so hard, and the factors affecting success are so diverse, we can never be sure of the long term viability of any approach. I just think we have to be both respectful of people who choose to back different approaches while also being frankly critical of the weaknesses of those approaches.

  2. Scott Abel (@scottabel)

    I’m not getting into the people are bailing out of DITA discussion (because I don’t see that in my corner of the world, at all), but I did grab one morsel from Mark’s post that resonates with me: “The truly revolutionary products meet requirements we have not been able to articulate.”

    That’s undoubtedly true. I see it in my daily life. We are limited by what we are able to see as possible, probable, or necessary (amongst other things). Plans designed to help us overcome challenges rely on us to be able to see — and articulate — the actual problems, not just the ones that are impediments to our daily, preferred routines.

    Disrupting the status quo in an innovative and imaginative way is seldom what happens when we put writers in charge or solving dilemmas relating to how corporate assets should (or shouldn’t be) managed. They are usually just too close to the problem to see the possibilities and unfamiliar with the opportunities available to them. Content is an asset worthy of being effectively managed by informed and involved stakeholders whose responsibilities include managing content assets in the same way they would manage other assets.

    Making writers responsible for articulating the future state of content is a horrible idea in most organizations, regardless of whether DITA is in the mix or not.

    1. Mark Baker

      This is fascinating, because I was thinking just yesterday that what is striking about content strategy is that it is largely an association of managers and technologists. Writers really don’t seem to play much of a role in it. “managing content assets in the same way they would manage other assets” really highlights this. Essentially, in this view, you manage content the way you manage soup or shoes or cabbages.

      Now this doubtless solves a lot of logistical problems for organizations, which is doubtless a good thing. But it also means that content strategy is dominated by a different mindset. As I wrote recently, we are now living in the age of the content manager, not the age of the writer, and that has its downsides as well. (http://everypageispageone.com/2015/09/28/the-age-of-the-content-manager/)

      The problem with treating content like soup or shoes or cabbages is that content is not simply a set of topics. Content is stories and stories are different from shoes and soup and cabbages. Stories are deeply dependent on other stories and therefore stories are related to other stories in ways that soup, shoes, and cabbages are not related to each other. Those relationships cannot be reduced to database tables or taxonomies. They extend not only between one story and another, but to readers, and the reader’s stories as well. And it is upon the success of stories that the success of content depends.

      Treating a story like any other commodity doubless brings a number of benefits, but it can do damage as well. It can harm storytelling and the storyteller’s morale. It can disrupt the relationship between stories, and between stories and readers, on which stories depend for success. Making writers alone responsible for articulating the future state of content may not be the best idea. But ignoring their voices is a horrible idea as well.

      1. Sarah O'Keefe (@sarahokeefe)

        Every specialist has the same opinion–that THEIR product is special and unique. Content strategy is about applying basic operational principles (Scott already mentioned assets and I’ll add manufacturing techniques) to your unique product class.

        Tony Self likes to talk about the transition from hand-made cars to assembly lines. There was huge resistance because of course the first cars off the assembly line were inferior to the hand-built ones. But the cost advantage ALWAYS WINS. (Other than niche markets blah blah.)

        Content has unique and special aspects. So does every other product in the world. The content strategist’s job is to integrate the business requirements with content principles in a useful way.

      2. Mark Baker

        Yes, every specialist thinks their product is special and unique. And every specialist is right. And yes, general management principles can nevertheless be applied to make their processes more efficient.

        BUT, those general principles have to be applied in a way that is sensitive to what is special and unique about the thing they are being applied to. The way you apply assembly line principles to building cars is different from how you apply them to building software or growing cabbages. (Assembly line is probably not the right term here: too specific to a certain class of products.) The cost advantage does not always win if the quality or integrity of the product suffers in the process.

        So, yes, the content strategist’s job is to integrate the business requirements with content principles in a useful way. And my point is that they are not always doing a great job of it. Content management is often imposed in ways that are insensitive to the nature of story and how stories operate and how they are constructed, related, and received.

      3. Larry Kunz Post author

        Mark, Sarah, and Scott: Thank you very much for sharing your comments and sustaining this conversation.

        I want to pick up on one of Mark’s points: that XML and DITA are especially unsuited to the telling of stories. Mark, in the past you’ve helped me see the centrality of storytelling in developing and delivering content. So this is a serious charge.

        Let me suggest that there are weaknesses in all of the technologies we’ve used over the centuries for storytelling. I don’t see how XML and DITA are inherently less suited to storytelling than Microsoft Word, or typewriters, or Gutenberg’s printing press, or papyrus scrolls. Even sitting around a campfire listening to the village storyteller had its limitations: the teller’s memory might be faulty, and the ground was hard and cold.

        In fact, because XML and DITA allow the possibility (through metadata tagging) of adapting content to the individual reader’s experience level and milieu, they might actually be better suited than most of the others. Just because most practitioners don’t (yet) know how to exploit that capability, we mustn’t simply dismiss XML and DITA out of hand.

      4. Mark Baker

        Hi Larry,

        Actually, my comment on stories was not about XML or DITA. It was about how content management handles the relationship between stories. It’s a theme I have been exploring over several posts on my blog. I won’t list them all, but http://everypageispageone.com/2015/06/15/the-war-between-content-management-and-hypertext/ and http://everypageispageone.com/2015/06/24/taxonomy-wont-save-us/ deal with the big issues.

        My issues with XML as a syntax and model for structured writing are entirely orthogonal to the issue of writing stories.

        DITA is something of a middle case. Its default structures are not good for storytelling and its approach to linking is far from ideal, but you could certainly make it work with the appropriate customization. I just think there are easy ways of doing it.

        The CMS model, DITA, and XML, both individually and collectively, solve some problems,create others, and leave other problems unaddressed. That is not in any way exceptional or unexpected. But it suggests that we should keep looking, trying other models and other approaches that might give us a better overall performance.

  3. Pingback: Involve and train your writers | Think DITA

  4. Pingback: Redakteure beteiligen und richtig schulen | Think DITA

  5. Pingback: Living and learning: 2016 | Leading Technical Communication

  6. Pingback: Lightweight DITA: I’ve seen the light | Leading Technical Communication

Tell me what you think

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s