Reasons Why a DITA Implementation Can Fail

Home/Publications/CIDM eNews/Reasons Why a DITA Implementation Can Fail

Chona Shumate, Cymer, Inc.

My team successfully completed a DITA implementation a few years ago, and we have experienced very positive results. We exceeded our ROI expectations with considerable time and money saved from our new DITA processes. However, based on recent industry surveys, companies are reporting dismal failures and significant decreases in their teams’ productivity. So, what happened to make our implementation so successful? I’ve had many conversations with other Tech Pubs groups and can share some insight as to what the reasons might be.

DITA Redefines Technical Writing

Adopting a single sourcing methodology and creating modularized, topic-based content is essential. However, truly understanding the value of being able to reconfigure your content is key to effectively implementing a DITA solution for optimum results. There is still a resistance to letting go of the book/manual/page mentality of writing. DITA requires a change in how you think of content. It may help if you think of DITA content being similar to software code—there are no “pages” in software. For my team, we learned that DITA lends its full value in the ability to re-use and re-configure content. Essentially, our documentation is a collection of markup language that is structured and assembled to inform. In contrast, software is structured and assembled to perform. As a collection of markup language, our documentation can be reconfigured as our products require.

By modularizing content in smaller pieces, you can reuse and reconfigure those pieces by applying metadata/properties/attributes (similar to how variables work in software). Because most of our products have similar content but not the exact same content, the Return on Investment in this capability is significant for us. Applying DITA specifications to our content development has given us a different mental model for technical writing.

A Reuse Strategy is a Must

Related to reconfiguring content is the need to map out your re-use/reconfigure strategy. This mapping takes some thinking ahead as to what configurations your products have or might have with features, customers, and audience level. You need to have a good understanding of how similar and how different your content is. A re-use strategy should be thought through first so you know how to set up and script your EXtensible Stylesheet Language Transformations (XSLTs). XSLTs are the instructions you give to your publishing engines about what to include or not include and how you want the content to display. XSLTs can do a lot of the work for you to automate your configured output. You also need guidelines so that your information developers know how to apply your re-use strategy. Our process is to create a generic procedure, then apply the metadata via XSLTs for the deltas (the different product configurations). We decided that if a procedure has more than 25 percent deltas across product lines, it becomes its own procedure.

Team Roles Change with DITA

You need at least 1 or 2 people on your team to understand the technical aspects of the DITA specifications, the Component Content Management System (CCMS) tools, and the XSLTs used to create the DITA output you want. I found this critical. A CCMS is different than a CMS, but you should know why. You need to know how to exploit your CCMS to set up your system to reconfigure the same content and how to leverage XSLTs with metadata—at multiple levels—to optimize your development and publishing processes. We reconfigure the same content into 13 distinct sets of ‘eLibraries’ based on customer, model, gas type, internal, external, and feature set. You also need to know the components of a CCMS and their relationships—the editor, publishing engine, database, XSLTs, and so on. It really takes at least one person who understands publishing from the system side not just the content. And note that other roles change too. In my team, the writers became content developers and ‘configurators.’ Our publisher became an information architect, XSLT scripter, database admin, and web designer. You either have to train or hire for these skill sets.

It’s Crucial to Know the Rules

DITA is about rules, and these rules must be fully understood so you know the ‘why’ for each rule, and they must be followed so you see the consistent benefit of repeatable processes and outcomes. Following the DITA specification is not optional for successful publishing. You need to know the basics behind structured documents and understand the rules of how elements work. The elements used for DITA-compliant authoring have specific relationships and contingencies with other elements. You can’t do your own thing with a DITA-compliant system, unlike Word or FrameMaker. The DITA specifications are just that—specifications that spell out the requirements for DITA authoring and publishing.

It is important to know that DITA is not for the faint of heart and isn’t truly learned by on-the-job-training (OJT). You need to read and interpret the DITA spec (or get an interpretation) and learn XML. I wouldn’t rely on your IT department or the WIZIWIG editor views to get by. If you don’t have the skillset or knowledge on board, invest in training. Hire a consultant to help you navigate through the transition from traditional writing to DITA-compliant writing.

Have an End Game

You really need to know the problem you’re trying to solve with a DITA implementation. Examine your writing and publishing processes to identify areas you need to improve. Form a problem statement and use that to drive your strategy and ROI. Do you want to reduce duplicated content? Establish more automated publishing to reduce human error and speed up the publishing cycle? Focus more on the quality of the content vs. formatting? We learned that we had lots of duplicated content, and it took us days to manually publish a full documentation set. It now takes us 12 minutes. Determine what the business problem is that you need to solve. Next, know what you want to do with your content. How do you want to deliver your content to users? Envision what you want your pubs to look like and make it happen with your strategy and tools. I hear from a lot of Tech Pubs managers that they feel they have to get on board with DITA but don’t really know why. And if the manager doesn’t know why, you’ll never get buy-in from the team who has to do the work and learn a new way of working. It’s a game changer, no question.

Finally, Take the Time for Everyone to Plan and Learn

A DITA implementation can take up to 18 months for a complete conversion–to-DITA project and longer depending on the volume of content. Take the time to do some research and benchmark. Benchmark in and out of your industry. Benchmark large companies and small, with different product types. Interview managers and their tech pubs groups who have a DITA implementation. I wouldn’t reinvent the wheel; a lot of us have already done this work. Study the DITA spec and attend webinars and workshops. Review CCMS product comparisons. Get familiar with terminology, and be willing to change your perceptions of what technical content is and can be.

A lot of mistakes are made from uninformed assumptions about DITA. Poor DITA implementations can be a result of not fully understanding DITA and the changes it will require for team roles and the discipline needed to adhere to DITA rules. If done properly, a DITA-compliant publishing environment can save time and money and allow you focus on the important aspect of technical writing: the quality of the content.