Stanley Doherty, Ph.D., Oracle Corporation & OASIS DITA Adoption Technical Committee
November 15, 2019

As change initiatives go, DITA is often described as being “highly beneficial and highly disruptive” for the organizations adopting it or making ongoing investments in it. As anyone who has been involved with a DITA migration or upgrade will attest, the “disruptions” always precede the “benefits”. Although a risk analysis should be at the heart of every DITA migration or upgrade initiative, we do not have a shared vocabulary for assessing it.

Let’s consider two organizations assessing risk:

  • Blivets-R-Us: The team at Blivets-R-Us has quadrupled its size in the last four years and quintupled the amount of content that it needs to publish at a near-continuous cadence. MadCap Flare has served them well since they were a three-person start-up, but is not scaling up to their requirements for content reuse, automated publishing, localization, and cross-functional collaboration. Although some team members have had prior experience with DITA and topic-based authoring, the group is, for all practical purposes, approaching their migration from Flare to DITA with insufficient in-house expertise. If most everything about DITA is a bit of an unknown, everything is a risk.
  • Legerdemain Trust: The Denver CO team at Legerdemain has been authoring in a no-frills implementation of DITA 1.2 for three years while their peer team in Guadalajara MX has just completed its first year. The teams want to standardize on an implementation of DITA 1.3 that would allow them to take advantage of key-based reuse and to dabble with branch filtering. Both teams have heard mixed things about using keys and are concerned that taking their DITA implementation to the next step might disrupt the success that they feel with their current implementation. The team is divided on whether it should just defy the risks and “go for it” or “spend a year gathering data”.

In each case, the lack of a data-driven, risk assessment can overshadow possible benefits. Teams can get stuck, especially if they lack the expertise, budget, or time to perform thorough, systematic research. Being “agile” or “lean” for many pubs organization is a euphemism for operating without support or a safety net.

David A. Shore of the Harvard School of Public Health[1] argues, “When leading a change initiative, you should focus on acknowledging, anticipating, and managing risk—instead of avoiding it at all costs.” Some of his best practices for risk management include identifying known risks, quantifying them, establishing a “no-go risk threshold”, and monitoring progress in understanding the scope (min/max impact) of each risk.

Developing resources for teams adopting DITA or increasing their investments in DITA is a lot of what we do on the OASIS DITA Adoption Technical Committee.[2] Although DITA has been around as an OASIS standard for 15 years now, we do not have a ready-to-download, risk assessment tool that would address issues such as:

  • Should we modularize our unstructured linear docs before converting to DITA or handle modularization as part of the conversion process?
  • How much rework will we need to perform on existing content if we implement a nifty new feature such as keys, branch filtering, or constraint specializations?
  • Beyond the simplistic examples for a new feature, are there hidden costs or dependencies that we encounter only after we are too far along to back out? Does it scale?
  • How quickly can content developers become proficient with DITA or with a new DITA feature? How would we know that they will be trained and ready?

Yes — resources such as the Yahoo DITA Group and mailing lists can be useful in framing some of these issues, but there is no substitute for teams seeing how their existing content integrates with DITA or with a new DITA feature. It’s all kinda scary until you kick the tires and go for a test drive.

The OASIS Adoption TC suggests that open-source DITA collections can be an important resource. We have been collecting references to these DITA documentation sets for a couple of years, verified that they build, and have recently posted an annotated listing.[3]

[1] What Could Go Wrong? How to Manage Risk for Successful Change Initiatives
[2] OASIS DITA Adoption Technical Committee
[3] Open Source DITA Collections (