5 Things Some Technical Writers Don’t Like about DITA

In one of my previous posts, I explained what’s so cool about DITA when it comes to formatting.

You are probably familiar enough with the topic and concept to know about the tremendous advantage DITA offers in terms of content reuse and single sourcing capabilities. So why are there technical writers who are not keen to move to DITA and even resist adopting DITA in their companies?

Based on our experience with implementing DITA for various companies, I would identify five reasons:

Reason #1. DITA changes the usual way of thinking
Not everyone is ready to move to a new mindset. Writing stand-alone topics rather than monolithic documents requires reconsidering concepts that many of us have been practicing for years. Let me mention some of them:

  • Inline cross-references
  • Introductory texts like “this section contains the following…”,
  • To do statements
  • Callouts placed on graphics

Sounds familiar? In DITA, handling all fo the above issues will be managed differently. I’ll explain why and how in my further posts.

Formatting is another area where DITA differs significantly from non-DITA documentation. Believe it or not, some writers do like to deal with formatting. They can spend hours and a lot of creativity make their documents look nice, the bullets positioned just this way, the headings spaced just like that.

DITA takes this function away from them. One of our clients found that their writers waste too much time on formatting and didn’t spend enough time  doing what they were hired to do – write meaningful and helpful content. This was one of the main factors behind that company’s decision to move to DITA. Not all the writers were happy, but it saved the company money. It was, most definitely, a cost-effective solution that ended up producing better documentation for the end-user. This emphasizes, by the way, that moving to DITA can definitely be considered a cost-effective, business solution.

Reason #2. DITA constrains the way of writing
For some people, the whole idea that DITA will put them in a framework in which they will be allowed to do only certain things, sounds scary. They believe that DITA will impose limitations on their creative abilities, their opportunity to enhance their documentation both in terms of look and feel, as well as their style of writing. They see it as a battle between DITA and their creative minds.

But  actually, it isn’t DITA that is placing these constraints on their writing. In technical writing, we are already following certain requirements. These are long-established requirements that demand consistency, demand patterns so that our users know where to look, what to expect.

Without DITA’s enforced structure, many technical writers simply ignore these rules. Part of that is time limitations and pressure under intense deadlines; part of that is the belief that no one will notice anyway. Those technical writers not using DITA, but still producing proper documentation already impose rules on themselves…they are simply less explicit than DITA.

Think of style guides or de-facto standards established in the industry or in a specific company. All DITA does is enforce these requirements rather than recommending them. And I can’t say following rules is necessarily a bad idea.

Technical writing is not creative writing. We say this, but do we follow it? If we do, it is because we realize that  we all are striving to keep consistency and therefore, have to limit the part of us that wants to make ad hoc, arbitrary changes that violate the rules.

Reason #3. DITA requires conversion of legacy content
The conversion stage is the moment of truth. This is the time when you (and not only your users) realize the cost of inconsistency in your documentation (see my post dedicated to XML conversion). Many companies see this stage as an insurmountable task and balk at moving to DITA even when all other factors confirm it is the logical move.

If you don’t want conversion to be a nightmare, one thing you can do now is take care of inconsistencies in your documentation now. Even if you don’t move to DITA, this is a useful and beneficial practice.

The better your documentation is, the more consistent it is, the easier it will be if and when your company does decide to make the move.

Reason #4. Customization of DITA output may require significant efforts and skills
That’s true, especially if your primary output formats are PDF and online help. Creating a deliverable with a default look-and-feel literally takes seconds. However, because the look-and-feel should conform to your company’s standards, this is when the real fun begins.

The situation can become easier if you just need to produce PDFs and already use FrameMaker. If not, customization of how the output looks and behaves can be a challenge, even for experts. The need for a well-documented DITA Open Toolkit (the set of tools for publishing DITA to multiple formats) is one of the hottest topics discussed now at the OASIS DITA Adoption Technical Committee. That means, even among those most deeply involved in DITA, there is an awareness that DITA’s customization abilities must be further enhanced.

Reason #5. DITA is not a plug-and-play solution
Many writers are looking for an easy-to-use solution that would work out-of-the-box and doesn’t  require much training. They take a look at DITA, understand the efforts, and even understand the benefits. But then, they decide to just go with another solution or  hopefully, more advanced authoring tool. Because the DITA solution isn’t something that seems intuitive at a first glance.

So they move from Word to Flare or to Robohelp, or to AuthorIT, or to Doc-To-Help, or to something else. You can open RoboHelp, press a few buttons, and import and create a help file. It works, so shouldn’t that be the solution? Of course, if you want to really customize RoboHelp’s output, you still need to really learn the application. Maybe you spend the time and learn AuthorIT – but you still have to port all your legacy documentation. Maybe you invest in Doc-To-Help or something else…but you still haven’t found an effective way to reuse massive amounts of text across projects and products, departments in your company, and even physically distant documentation teams. Eventually some of these writers realize that they may have solved some of the initial problems they identified, but other fundamental problems actually persist.


These products are all plug-and-play tools indeed. But just in terms of installation. The problem may be wider and not necessarily caused by a specific tool. If the problem is caused by the methodology of your workflow with the content  and you are continuing using this same methodology with a new tool, there is little chance that the problem will be eliminated. So installation of a new tool alone doesn’t solve the problem.

In this sense, there are no plug-in-play solutions at all. There are plug-and-play tools, but solutions needs to be built, customized, implemented – whatever it means. It might mean moving to DITA, finding more effective use of the existing tools, or purchasing another tool. By the way, there are plug-and-play DITA editors, but we’ve already found you’ll need more than that.

If it’s so complicated, why are companies adopting DITA? And why are even small documentation teams moving to DITA? They are indeed – we have helped several companies do this even though they have small documentation teams (even single, lone writers). In the next DITA-related post, I’ll tell you 5 reasons why management likes DITA and why DITA shouldn’t be something that technical writers avoid.