There's a trope that says, if you want to do good content delivery, you have to advocate for methodology, not tools. (This is often said in despair by someone dealing with a team of writers determined to find a way to use FrameMaker to make pizza crust.) To that end, advocates of DITA—the Darwin Information Typing Architecture—advance it as a methodology, rather than any particular or specific set of tools.
This is not quite correct.
DITA is an XML vocabulary. The "XML" part brings with it with a large collection of general-purpose XML tools that are as happy to manipulate DITA-flavored XML as they would be to manipulate any other flavor of XML. This is a very cool thing because this inherited generality is what makes DITA able to support multiple methodologies.
You can use DITA to do single sourcing, build information quality state machines to manage your content, deliver content using scenario-based authoring, increase productivity by factors of two or three, and many other things.
Any of these things have obvious business cases, and people talking about the benefits of DITA will discuss them with glee and delight.
I want to talk about how DITA is hard.
DITA isn't technically difficult; XML as a whole is a collection of solved problems, starting with Unicode, passing through validating XML editors and XML-aware content management systems and ending with content formatters that will produce PDFs in East Asian languages as happily as European. DITA gets to take advantage of all of the "parent" XML solved problems. Everything is still trade-offs, you have to think about and quantify your requirements, and you may sometimes have to pick one thing over the other as a matter of a technical choice. Time, money, and skill, and not really a lot of any of them relative to the size of the benefit, will still solve any of the technical problems you will encounter setting up a technical authoring system using DITA.
The hard part is recognizing that using DITA effectively means doing topic-based authoring with strict form/content separation by means of semantic tagging of content, instead of narrative writing in a WYSIWIG tool that combines form and content.
This difference of methodology changes some very basic things about technical writing. These changes produce the reasons a successful DITA deployment is hard:
- There is no business case for pretty.
- The thing you are writing is your archive format, not your delivery format.
- You no longer own a document; no one person owns the whole document delivery for any delivery format.
- Your writing team is undergoing a skills reset while at the same time being confronted with comprehensive quantified metrics for their performance.
If you want your DITA project to succeed, you must deal with these difficult things.
No Business Case for Pretty
If you want your DITA implementation to meet business goals of increased productivity or reduced delivery times, you have to use form/content separation implemented by means of semantically tagged XML content. (The XML describes what the content is, not how it looks.) Using DITA's very basic mechanisms for specifying output appearance converts a clean XML form/content separation into something that is a very bad word processor. In terms of the business goals, and by analogy to modern HTML best practices ("use a stylesheet to specify appearance"), this will make intellectual sense to your writing team.
For the last 20 or so years, ever since what-you-see-is-what-you-get desktop publishing software and word processors became widely available, technical writers have been evaluated on how good their work looks. This is often an informal part of the evaluation, but the steady pressure of reviewers and customers expecting work that "looks like a book" has created a deep expectation that what matters—the thing that is necessary to avoid being yelled at—is pretty output.
This has also produced a lot of people working in technical writing for whom producing pretty output is the part of their job they really enjoy, or for whom the mental exercise of managing content structure is extremely difficult without being able to view the final delivered appearance.
Making form/content separation by semantic tagging work means having automated output generation you can rely on without marking up the XML with formatting instructions on individual elements, looking for a DITA GUI output-tweaker app, or introducing a manual post-production tweaking pass to "hand finish" your PDF output.
It means not caring about pretty.
Not caring about pretty is exactly the right thing to do in business case terms; you don't have a business case for pretty. ("Pretty" is not the same thing as "legible" or "consistent"; someone has to do the design, and build the output processing, to give you clear, legible, and structurally consistent output for whatever output formats you need. It's just that this someone isn't on the writing team, and their steps in the process happen after the writing team is done, finished, and gone on to the next thing.)
If you're using DITA, you really don't have that business case for pretty. There are a small number of industries, such as fashion reporting or primary school textbooks, where pretty matters. These are not industries where you would use DITA to do technical authoring, and in an industry where you would use DITA for technical authoring, there's a business case for fast, a business case for correct and complete information, and a business case for consistent presentation. There is no business case for pretty because pretty isn't something your customers would pay for. (Remember that "waste" is anything you do that is not at least one of legally required, inescapably necessary to the operation of your business, or something a customer would pay for. For technical authoring with DITA, pretty is waste.)
Nobody ever bought a computer system because its documentation was a masterpiece of book design. They'll curse it or you if they can't read the documentation, find what they need in it, or if it's visually oppressive, but the documentation is not what convinces them to spend thousands and thousands of dollars on a new piece of IT.
Having no business case for pretty isn't the problem. That's using DITA as designed, where you stick to the form/content separation and don't put in formatting information and don't hand tweak your output. The problem is that not doing work to make the output pretty will provide your writing team with a subliminal sense that they are going to be yelled at. They will become twitchy and cantankerous until they can do something to abate that sense of impending doom.
If you want to have a successful DITA deployment (in the "doubled productivity" sense of successful), you have to address this emotional unease, because otherwise your writing team is going to be determined to turn DITA into a very bad word processor, and DITA, which for complex historical reasons inherits many of the munge-form-into-content markup possibilities of HTML 3.2, can actually be a very bad word processor. Just using DITA will not inherently save you from this problem.
Formally addressing the whole "yes, really, we've decided we don't care about pretty" business decision to the writing team (and being patient with their dubiousness); suppressing, by the least sufficient means, any engineering managers who really want the documentation to look like a graduate level textbook from their specific field and are nagging the writing team for non-semantic changes; and putting the time and energy and focus into evaluating, across the whole writing team, quality of semantic tagging rather than specific appearance of output, will all be required.
It will still take at least a quarter and more likely a year to really convince everyone involved that the basis for evaluating writer effort has changed from "pretty" to "good semantic tagging" and "clearly represented information" and "lots of re-usable topics"; this is a very difficult transition for almost anybody not already solidly familiar with semantic tagging and form/content separation in documentation delivery.
This Is Your Archive Format
With any kind of WYSIWIG software for content delivery, there is a close relationship in appearance between your writing format—what you see in the WYSIWIG software—and your delivery format—the PDF or HTML styles you ship to your customers.
With DITA, this close relationship is broken. Your DITA XML content is one of, rather than all of, the inputs to a process that produces your delivery format. (And yes, something like WebWorks sort of emulates this process by mapping existing styles in a document to HTML styles. But this is converting between delivery formats—the styles with their formatting are already there—rather than generating a delivery format from semantically marked archival content; the generated delivery format can create content, delete content, or re-order the content, it's not a straight one-to-one translation.) As a writer, you do not control, and probably do not know, all the other inputs to the process generating the delivery format.
What you're producing when you write DITA topics is an archive format; this is how this information will be stored, and searched by you; the version your customers get is the result of further processing. This further processing very probably includes content deletion or reordering, and this further processing is outside of the responsibility of the writing team. It might not be outside the responsibility of the documentation manager, but the writer and editor roles as roles should have nothing to do with it. Making the delivered document formats is not what they do. What the writer and editor roles do is make sure that information is recorded correctly in a consistent semantic tagging, and grouped so that individual topics can be re-used anywhere in a map without needing to be changed.
This is a very large change in basic writing objectives. Your writers go from a scenario in which "this is what the customer sees" to one in which "this is the information that will be presented to the customer by some automatic process we don't control". It sounds trivial, or even like a distinction without a difference, until you start to do it. When you start to do it, you'll find out it's hard to do.
One example of the change in mindset that makes it hard to do: in XML, white space is, by default, insignificant. Processing can and will collapse multiple spaces, tabs, or carriage returns into single space characters. The traditional way to introduce a break in a long title—by adding the carriage return—won't work. This is a good thing—you do not, after all, know all of the ways that DITA topic will be processed and delivered in the future; you might not know all of the ways it will be used now. So you don't know where or how the title should break, even if you know where you want it to break in the delivery format you're immediately concerned with. This good thing is not likely to seem like a good thing to your writing team; it will conflict with long-established habits. (You can do clever things with Unicode space characters to get around this particular issue. Unless you are doing so to tell the output processing "these are the acceptable places for a break by natural-language rules", you shouldn't. You should either have the people responsible for the output processing fix it or use shorter topic titles instead.)
Another example is that in DITA, there are no heading levels. Everything is a <title> element. Your maps, topics, sections, and humble figures in those topics all use the title element to indicate "this chunk of text should be processed as the heading of its associated parent element". It is up to the output processing—not the writer—to produce a deliverable document that figures out how to present the title text to convey to the customer "this is a heading". This is a tough adjustment; it is necessary to believe that the output processing will get it right, to stop thinking of the writing process in terms of chapter or document position, and to accept that in a topic-based authoring system, eventual topic position is arbitrary; someone else can use your topic somewhere you never expected.
The output processing will work, too, but this is because XML is restrictive, not because DITA is permissive. The thing that allows confident auto-numbering and auto-linking in DITA is all the stuff XML won't let you do, not what it will.
The whole scope of the "this is the bread dough, not the cinnamon rolls" mental adjustment takes time and some conscious effort; the thing you're creating when you write in DITA is an information archive. Creating the content deliverable from some specific information set taken from the archive is a different production step, in principle able to be done by different people who don't even need to talk much to the DITA-using writing team.
It's Not Your Book: Giving Up End-to-End Document Ownership
Many—not all, but many—technical writing teams find themselves dividing responsibility by delivered document. Fred does the user guide and Mary does the installation guide for each new product, sort of thing. This has the advantage of predictability and familiarity; everybody always knows that they're doing and they will get to know the people from whom they need to receive information pretty well.
Efficient use of DITA means not doing things this way. "What topics do we need to deliver?", "What goes into this topic?" for each of those topics, and "In what arrangement do we present these topics to our customers?" are all different questions, and making one person answer all of them works poorly compared to an approach that uses staged production and divisions of labor.
Handling complexity is expensive; you have to think about more things, and more interactions, and it's easy for the number of interactions that need to be considered to get out of hand so that you're spending most of your time and effort controlling change rather than doing productive work. Reducing complexity, and, more importantly, giving people tasks in which complex questions are not interacting, helps enormously with productivity. So having a relatively junior writer producing assigned topics—ideally knowing the intended customer-use scenario, but not the map or maps where the topic will be included—while a more senior writer or editor edits these topics and constructs maps from them, and a team lead or manager role negotiates the "what topics do we need to deliver?" question with the rest of the organization, permits several advantages.
Individuals have less complex, more constrained problems, and do not need to consider information that is out of their scope of concern.
Complexity management overhead is diminished, and proportionately more effort can be devoted to production, rather than to keeping track of what you're supposed to be doing. Pitching unnecessary complexity management is a lot of where that "doubled productivity" successful DITA deployment comes from.
If your CMS supports per-role assignments on individual content objects (topics and images) and maps, you can break a large project into specific assigned tasks for each stage of production.
- Management gets a clear, quantified picture of "how done is this project?", rather than getting a best-guess percentage answer from the writer assigned to an entire document. Especially for new products and unfamiliar information delivery requirements, this makes it much, much easier to deliver information on time.
- Management gets a quantified picture of how much load—how many topics -- each writer is handling. There are likely to be some surprises in this information.
- The writing team as individuals know exactly what to work on and in what order. Because the pieces are small—the whole point of topics is to be the smallest meaningful unit of documentation—you can throw away the customary pattern ("Fred always does this; Mary always does that") and assign work to meet the schedule. It doesn't matter if Fred and Mary's topics are going into the same or different maps.
- Detailed planning becomes practical. Instead of "the document takes about three weeks", you have a precise (by the law of large numbers, eventually very precise) idea how long each individual topic will take. When the larger organization wants 12 more topics to make a customer happy, you can say "that takes another two days, plus however long the reviewers take", and back this up with hard numbers when the larger organization wants it to take zero time. You can predict at the start of a major product's development how much work it will be to produce the associated information delivery, again with hard numbers in support, and ask then for the required resources, rather than having to plead impending doom half way through the information development process.
That's all an enormous net benefit to the writing team. To individual writers on that team, it can feel like a demotion ("not trusted with a whole document anymore"), an imposition (I have more to say about the metrics in the next section), or a loss of a control or responsibility (It might still be their map, but it's not their document anymore; someone who used to feel like a peer now gets to ask them when their topics will be done, or to edit them and send them back for correction; not knowing where their topics will be used makes some writers very uncomfortable).
This one is especially tough from a management perspective, because you're not going to get your new process perfect on the first try. You're going to want to adapt and change it, and members of the writing team are going to want different things, including "put it back the way it was before this DITA stuff!" when changes are made. It's a difficult balancing act to keep the DITA-driven topic-based, scenario-based, and staged-production benefits while keeping the writing team happy with the radically changed organization of work.
Having Lots of Quantified Metrics
If you want to use DITA effectively, you're going to adopt a CMS along with DITA. (Effective topic-based authoring means having an automatic way to answer "Where is that topic Fred was working on last Thursday?", along with many other sorts of meta-data.)
Once you've adopted a CMS, you suddenly have productivity data—topics per writer per time period, topic re-use rates per category of published document, user complaints per topic (that can be mapped back to specific writers, reviewers, and editors), etc.—that can and should drive management decisions about your writing team.
Especially because topic-based authoring, DITA, and XML function as a start-again on most skills—core writing skills may transfer, but the software platform can and should be completely changed from the incumbent WYSIWIG process—any writing team shifting to DITA authoring has the potential to feel very insecure. It's a new process, new tools, with different goals—information delivery by effective topics is a very different proposition from document delivery in WYSIWIG tools—and to go along with that they're suddenly also being inescapably and continuously evaluated by the tools they have to use to do their new job.
The writing team may not like this much.
The management problem, like most management problems, collapses nicely into clearly expressed expectations, unambiguously set quantified expectations, and finding ways to reward desired outcomes.
Which is theory; your actual DITA adoption doesn't happen in theory. It's hard for anybody to go from ten or more years of experience with their tools and processes to zero, all the while being expected to keep producing. (Your larger organization is going to expect "producing more and faster", since that is going to be a significant part of how the capital expenses for the CMS were sold as a business benefit.) It's especially hard if it's obvious that the quantified metrics for productivity and effectiveness are going to change the existing value-of-contribution hierarchy for the writing team. That is not certain to happen, but you should emphatically not approach the DITA transition on the assumption that it won't.
All you can really do from a management perspective is to be sure you're out in front of this set of issues. The business requirements compel the most effective use of the DITA tools and processes you can make, HR evaluation processes should already rest as much as possible on quantified performance metrics, making use of the CMS-supplied performance metrics more or less inescapable, and there are a bunch of positive uses you can make of those CMS metrics ("This reviewer? This reviewer is a bad reviewer. Let me take these numbers, and talk to this reviewer's boss for you...") which should be emphasized to your team. You should also point out that the performance metrics, on an appropriate time scale (quarterly is safe; monthly may or may not be OK, depending on external factors like product release schedules) are fair. They may not produce the results people expect, or that individuals want, but they're going to be accurate, statistically significant, and thereby a fair measure of productivity. (If that isn't going to be true, you picked the wrong CMS vendor. Try hard not to make this mistake, because not being able to answer "and how well is your DITA process working?" is a bad place to be.)
Conclusion
DITA is technically straightforward. It presents significant process, professional, and management challenges to a writing team. The effectiveness of your solutions to these issues will dominate technical issues in determining the success of your DITA deployment.
About the Author
Graydon has a degree in computing science, maintains an abiding interest in information delivery processes, and continues to find thinking in trees pleasant and relaxing. He was responsible for the functional design, deployment, and output generation of the successful AMD DITA CMS project, has deployed scenario-based authoring with reStructured Text and Python docutils in a month twice now, and wishes more people knew XPath. He is currently doing DITA and XML consulting work.
Key Concepts:
best practices, dita, multichannel (omnichannel) publishing, single-sourcing