10 DITA Lessons Learned From Tech Writers in the Trenches

This exclusive and informative top ten list is based on interviews conducted by TheContentWrangler.com with technical writers at more than 20 software companies—tech writers that are actually using DITA to create documentation today. It’s jam-packed with useful advice, practical tips, honest warnings, and lessons learned. No marketing blabber. No hidden sales agenda. No name dropping. Just straight forward and useful information no software company is likely to share with you any time soon. Ready? Let’s begin…

#10 – DITA Is NOT A Magic Wand

• DITA is a standard data model not a magic wand that automatically solves all your problems.
• DITA makes some things easier but adds its own issues as well.
• As with any XML project, the most effective solutions will be built by someone who has proven knowledge and experience. DITA does not change this.

#9 – Don’t Fall In Love With Software

• Far too many technical writers fall hopelessly in love with an authoring tool for no apparent business reason.
• Software love affairs are good for vendors because they convert regular, ordinary writers into mindless, unpaid software evangelists.
• Love affairs of this sort are bad for organizations that employ technical writers because they prevent us from asking questions about our own choices, our own motivations, and the impact our personal preferences may have on the organizations for which we work. Love is an emotional thing, while business is about return on investment, profit and longevity.
• Technical writers don’t know how to evaluate tools that support DITA. Most of us don’t know how to create a business case, collect metrics, nor how to determine how tools will impact the way we work. We don’t know what training we need, what it will cost us, and who we should—or should not—hire to help us. Its no wonder we gravitate toward the tools we think others are using without any idea whether those tools will really address our specific business needs.
• Don’t buy a software tool without finding out two things:
  1. if it will meet all of your business needs
  2. why, specifically, other products do not meet your business needs.

#8 Don’t Jump in Without a Clear Business Case, a Repeatable Strategy, and Measurable Goals

• Moving to structured content production is perilous with or without DITA. Poor planning can doom a project before a single line of code is written or a single purchase order signed.
• It is a sad fact that when I worked as a consultant the majority of Requests For Proposals and Requests For Quotes I saw were well-intentioned disasters comprised of a haphazard mix of features, technologies, and business objectives. While good intentioned, the sum lacked any vision and often missed critical items that threatened to derail the project.
• It is only sensible to move to DITA if you have a good reuse strategy in mind. If all your authors start producing topics with one particular manual or product in mind like they are used to doing since they wrote monolithic documents for one particular product or audience before, reuse will be limited and lots of similar content will be written multiple times … and will be reviewed and translated multiple times.

One Writer’s Business Case Adventure

I’ve been griping about our inefficiencies in creating documentation for years. A few years ago I complained to my boss that we needed to change the way we were doing things before things got totally out of control. He asked, “Why exactly do we need to change?” When I explained our challenges and why they we needed to change, he nodded as if he understood. Then he asked, “How are you going to overcome those challenges and make the changes you need? Do you have a plan of attack and some estimates on how much money and time we are wasting and what things you think you can do to change things? And, what return on investment do you believe we can achieve for these efforts? Without a formal strategy, you’re simply winging it and that’s no way to run a business.”

I retreated to my cubicle in a daze of business jargon. I’m a documentation manager, for goodness sake, not a business analyst! But, I have to admit I was embarrassed because his requests didn’t seem outrageous. But, I honestly had no idea how to do what he asked of me. I sought help from those with experience building businesses cases and was able to learn how to show why we needed to change, what the financial and other impacts would be to the business, outline how we were going to accomplish our goals and estimate what it would cost.

When it was all there in black and white my boss asked, “What took you so long to spot these issues? We need to make these inefficiencies go away and start using the money we put into documentation department more wisely.”

I won that battle and have been able to begin a move to DITA as a result. Making the business case and starting with a strategy have helped me get the attention of management and the respect of my co-workers. As soon as we adopted a strategy, we were able to see things we could not see before. A strategy defines where you want to go, identifies where you are today, and maps out how you are going to make the improvements you need. Without a formal strategy, you’re simply winging it and thats no way to run a business.

#7 – While You Are At It, Get A Content Management System

• Before we adopted DITA the reason we needed a content management system was unclear to me. But now, I can more clearly see the value of our CMS, perhaps because DITA forced us to think through our content life cycle and to examine the ways we could improve our processes in meaningful, measurable ways.
• While I can’t say whether all organizations should use DITA with a content management system, it sure makes sense to consider building a business rational for DITA and another for DITA plus a CMS. In most cases, I’d say adopting DITA and managing content with a CMS is a no brainer.
• DITA without a content management system is dangerous. You need to assure validity of content and prevent invalid content from being checked into the repository.
• I’m not sure why anyone would move to DITA without also moving their content into to a content management system. When you add the savings and productivity gains adopting DITA can provide to the savings, productivity gains and other improvements a CMS can provide, the return on investment opportunity is hard to ignore. There may be change management issues to consider in change adverse corporate cultures, but these issues can be overcome by employing change management best practices and a little common sense.

#6 – DITA Needs to be Constrained

• DITA allows authors to do things your business needs and authoring style guides may forbid. For example, DITA allows authors to create consecutive bulleted lists. We had to develop a way to prevent authors from being able to do that.
• DITA without constraints allows authors to introduce consistency problems. We all know authors create their own workarounds and that many authors know there are no style or structure police to stop them from breaking rules. So, select an authoring tool that can help you prevent authors from doing things with DITA that you don’t want them to be able to do.

#5 – Some Writers CANNOT Write Reusable Content

• Authors accustomed to doing formatting tasks on their own via a word processor or desktop publishing tool will need not only technical training but also assistance in understanding how and why their role has changed.
• Technically DITA is a very sound approach, but you need to consider the psychological impact on writers. Writing in books, chapters and sections is a very different approach than creating DITA topics and topic maps. Many of us started working with a minimal document approach several years ago, but you should consider the impact DITA has on a writers ability to conceptualize topics and topic maps as separate but dependent on each other to produce a final deliverable.
• I found that authors who did not understand the reasons behind structured authoring often directly or indirectly resisted the move. Authors were moving to a new way of working which fundamentally changed the nature of their jobs, so such resistance should not be unexpected. The key is to prepare for these challenges throughout the entire process of deploying a project.
• Keeping authors involved and informed goes a long way toward making the transition smooth. Managers must also be prepared for this and provide appropriate training and support as their writers make the transition to XML.
• Far too many software companies fail to highlight the change management issues that can crop up when making a move to DITA. The fact is, some people don’t like to change, don’t want to change, and aren’t going to change. Unfortunately for these writers, their world and way of working is going to change with or without them.
• When you make the move to DITA, there is no room for deviation. It is all for one and one for all. If you have loose cannons trying to do things differently, you ARE going to have problems and may have to make staffing changes.
• Authoring for reuse is different. Each topic must be authored as a standalone item. If you think this is no major feat for some technical writers to accomplish, a move to DITA will definitely show you who is—and who isn’t—capable of thinking in the ways DITA requires.
• My lesson learned: 1 in 4 of my staff of 20 could not make the move. They just can’t separate the old way of writing narrative content. And, if the truth be told, they don’t want to.
• For writers that are able to grasp the concepts and change the way they work, their jobs become progressively easier, and most authors began to like being guided by the structure, rather than being restricted by it, and enjoy not having to worry about presentation.
• The main difficulty writers had was to make the switch to writing topic based material. We were used to writing documents for a particular product or particular audience where we now write topics which may fit in multiple publications for different products and different audiences.
• Writers unfamiliar with XML required training to become familiar with total separation of content from style as well as a defocusing of presentation. It also took time to determine which DITA elements produced the desired transformation results and which employees could actually make the change without the need for additional training.
• We’ve found that continuing education —monthly training sessions—have helped us more quickly identify and overcome critical issues related to our move to DITA. And, it seems to be increasing the confidence of our entire team.

#4 Plan for Legacy Content Conversion Issues

• Don’t assume your content is universally formatted—it’s not.
• I was surprised to find out how many different and creative approaches authors use to create content. Even though we had clearly defined styles, rules and templates, they all found ways to workaround our rules, perhaps unintentionally.
• If you think your content is consistently formatted, think again. Odds are, you are wrong. You may have style and formatting conventions designed to guide authors in the creation of content, but chances are they aren’t being followed. This is a huge issue when moving legacy content into XML, especially when migrating from unstructured content into a structured environment like DITA.
• We bought into the whole notion that a software product could automatically convert our unstructured content to XML! What a joke! While using the tool did help us discover lots of inconsistencies, we still spent weeks cleaning up the content after it was converted. My advice for those who are about to move to DITA, include extra time—perhaps more than you think you’ll need—in your project plan. Then, if you decide to use a tool to help you convert legacy content, make sure to realize that you’ll need resources to tag your content up and address other post-conversion issues.
• Conditional text can be difficult to reliably convert. Cross-references can also introduce problems. We had to call in an expert to help us figure this out after the fact.
• Perhaps our biggest challenge was reworking the legacy data we had. We needed to convert the monolithic Word documents into topic based publications. Fitting the legacy content into the more constraining DITA topic structures is not always straightforward. We deliberately choose not to automate this process which forced us to review and rework all our content. This process has undoubtedly improved the quality of our documentation.
• Consistency is not an option when you are converting legacy content to DITA. All overrides must be removed. It doesn’t matter if your boss says they’re okay. They’re not and they will cause you problems.

One Writer’s Legacy Content Conversion Process Timeline

It took me 100 hours to convert 400 pages of unstructured FrameMaker content into DITA. The approach I took was to:

1. Clean up the styles in the source FrameMaker files (16 hours)
2. Create a mapping table that mapped these styles to DITA elements (8 hours)
3. Use the mapping table to get from unstructured to structured FrameMaker (1 hour)
4. Save the structured FrameMaker files as XML (1 hour)
5. Clean up the XML files to make them parse (24 hours)
6. Perform manually what didn’t come across in the conversion—see below (46 hours)
7. Create ditamaps for each book (4 hours)

I had to do the following tasks manually:

• Apply hierarchy to nested topics and lists
• Re-apply cross references
• Cut-and-paste table cell text
• Add graphics

Using this writer’s legacy content conversion metrics as a baseline:

• Converting 400 pages of content would take 100 hours (or 2.5 weeks)
• Converting 4,000 pages of content would take 1000 hours (or 25 weeks)
• Converting 40,000 pages of content would take 10,000 hours (or 250 weeks)

#3 Resist the Temptation to Specialize

• Specialization is one of the best things about DITA, but it is also the least understood. Writers were not trained to understand the concepts involved in specializing DITA. As a result, specialization efforts are prone to error.
• Specialization requires a lot of discipline. Until we have specialization wizards to help us correctly implement DTD changes that are needed when you specialize DITA, we will continue struggling to conceptualize what specialization is and how it works.
• Specialization is NOT the place to start. Begin by using the basic topic units, combined with extra namespaced attributes that will not break the standard. When you have done so for a while, you can make an informed decision on whether to specialize or not, and how to do so.
• In the first phase when we started writing the user guides and configuration manuals no specializations were required. We deliberately tried to stick to the standard topic types forcing us really to think about the topics we wrote. Does the content we are writing really fit into this topic type or is it more suited to transfer this into another topic? This was a question we often asked ourselves. Recently, specializations have been made to write the API documentation. In this documentation, functions have to be described which developers can use in their custom applications. For these we needed a specific topic type allowing us to describe required input, parameters that need to be provided when using the functions or procedures, and that would allow us to document the accepted result or output.
• So far, we have not had to specialize DITA for our on-line help or documentation. Of course, we are a software company and IBMs original development was for software documentation, so the fit is excellent. For our training materials we added specializations for a new infotype for a training module as well as some structural specializations to better match the Reusable Learning Object (RLO) concepts.
• Unfortunately, writers don’t often come to the table with the ability to think in the ways that specialization requires. We have always been the go to folks for expertise on writing. Yet, we don’t have the training and experience to fully understand the negative impact we might be having on our organization if we are making bad choices about what we specialize.
• Specialization can be powerful, but each one takes additional effort in maintenance, migration and support.
• Force yourself to rigorously justify each specialization. Ask for impartial opinions from others in the community before getting too deep. Make documentation of the system an ongoing activity. Dedicate resources to make sure any specializations or other customizations are recorded in detail.
• Be aware of specialization: only specialize DITA standard information types when really required; the standard information types provide enough flexibility to cover most of the regular content you produce.
• One important lesson we learned is not to rush into specializations. We tried to stick to the content types which are readily available. This forced us to really think about whether the content we wrote really fit in a given type Does this extra explanation really belong in a Task or should I not create a separate Concept for it. This resulted in a better organization of our overall content providing us with topics which are much more suited for reuse.
• Stick with the open standard as much as possible, minimize specializations, and use industry specializations from the public domain when possible.

#2 Hire an Expert

• Don’t be afraid to ask a lot of questions. We are a software company and we still found it necessary to hire someone to help us avoid making the mistakes inexperienced folks make. We also knew bringing in a resource would help us get to the finish line faster. Moving to DITA is a serious business decison, not a project for a curious tech writer to work on in their spare time. If you don’t dedicate proper focus and resources to DITA, you’re asking for trouble.
• First of all, typical tech writers do not “get” DITA. Most of them haven’t a clue how to lead such a project, nor should they be expected to do so without help. Dedicate resources to building an understanding of structured authoring, DITA and XML with your staff. Find trusted consultants but dont be afraid to challenge them. Seek out multiple opinions if you come across big issues.
• It is often difficult to weigh the consequences of decisions you make when starting a project until the end—and then it may be too late to fix. If you find yourself in a roomful of people saying things you don’t understand, find a trusted ally to translate for you and learn from them.
• Experts can help you understand things like inheritance, a critical feature of DITA. Without an expert to guide you, it is easy to misunderstand a concept or you may fail to fully appreciate its power.
• We took off down the DITA road alone, and had to stop to catch our breath. When we did, we called in an expert and got ourselves back on track. With a little rework and some training, we were able to recover quickly. Our biggest mistake was trying to get by cheaply. Of course, it ended up costing us more in the long run than it needed to.
• We thought like many others, let’s just send one person to training and he’ll come back and train everyone else. In retrospect, there are so many things wrong with that idea, I realize. At the time, it seemed like a good idea.
• Moving to DITA requires that everyone involved be educated to approach your challenges from the same vantage point Putting myself in the shoes of someone who hasn’t used XML at all, I think the quickest way to get up and running is to have someone with XML experience help you get up and running and be available for follow-up questions. An expert with DITA experience can help you in all kinds of ways. They should help you avoid the major mistakes early adopters have made and thus save you time and money in the long run.
• It’s always best to adopt a strategy before tackling any content project. I’ve heard this refrain many times before and I knew it to be true. So, we brought in a consultant who has years of experience and lots of street credibility. They helped us realize that DITA was not a stand alone project but part of a larger content strategy. As a result, we are now creating DITA content in several departments and using XML to help us do more with less. The technical publications department is now more intimately involved with all projects at the strategy and planning stages. In fact, we’re helping to lead the way our organization manages all business critical content, not just tech docs.

#1 DITA Changes Everything: Getting Up To Speed Requires Commitment, Effort, Skills, and Training

• DITA changes everything. So, ask yourself, “If I changed everything about my life, how long would it take me to adjust to those changes? How much time, work, and money would be involved? And, would every change I made be a good decision?” If you plan to move to DITA, be ready for some pretty major changes.
• Moving from unstructured to structured authoring is a formidable task. Anyone who tells you otherwise is uninformed or lying.
• It kills me to hear all of these DITA gurus chatting away on the listserv, oversimplifying the move to DITA. ANT? Eclipse? What the heck are these things? My writers haven’t a clue, nor should they have to. Don’t think the early adopters are representative of typical technical writers—they aren’t.
• Installing and using the DITA OpenToolkit is not something a Robohelp jockey or FrameMaker single source guru has any knowledge of. In fact, trying to use DITA is really confusing even if you have a software development background.
• A relational database guru may have to re-learn how they look at data to adapt to a hierarchical model. Programmers unfamiliar with functional programming may struggle with the concepts behind XSLT or XQuery. When employees have to struggle to understand how something works they are not as productive and oftentimes they become frustrated and unwilling to get behind the effort. DITA introduces changes that will affect writers and developers differently. Plan for the change and allow time for real learning. Don’t toss DITA at your staff and hope for the best. You’re likely to find yourself in a big mess.
• As a documentation department manager, moving to DITA is likely to be the hardest thing I’ve ever done. Would I do it again? Yes, I would, perhaps sooner than later. Although moving to DITA was a challenge—insurmountable for some of my employees who could not overcome the new ways of thinking it demands—it is providing considerable benefits to our organization and the customers we serve.
• Writers need training to avoid the many pitfalls that are possible. For instance, when moving to DITA, writers will need to know not to use traditional cross references and instead, use a relationship table in the map.
• There are many things that will change when you make the move to DITA. There are new things to know about creating content, linking to it, printing it, storing it, accessing it, and revising it. While some folks would have you believe these difference are not major hurdles, only you can determine what your staff is able to do and what training they’ll need.
• Don’t skimp on training, or you’ll be sorry later. Reading a book or taking a one day seminar may not be sufficient for most writers. If my experience is any indication, moving to DITA is a major change that requires expert guidance and lots of training in several areas—not just learning about the DITA specification, which can be a challenge to many writers in itself.
• DITA changes all kinds of things. Tools don’t always work as expected. Employees get frustrated. Timelines sometimes slip. Processes changes are needed. And, if you need to document those changes, you’ve just created more work for yourself. All of these changes are beneficial, but in organizations that are struggling to meet deadlines and where change is not embraced, this type of project can introduce a lot of stress and labor. It’ll all be worth it in the end, just remember to keep the end in sight.