top of page

True and False about DITA, Part 2

Updated: Feb 20, 2023

In the previous post, I talked about some popular beliefs about DITA. Today, I’m exploring some more of them.

DITA requires a significant learning curve


There’s a learning curve, but it’s not related exclusively to DITA elements. If you are coming from writing big monolithic documents, the biggest shift would need to be done in your mindset.

Writing stand-alone reusable pieces of content that follow a standard structure requires a different way of thinking. It’s a different paradigm that doesn’t depend on a specific content standard or a specific tool. It’s about how you organize your content in a way that lets your users find solutions to their problems easier and faster.

One of our customers hired a trainer who taught their documentation team the principles of minimalism, information typing, and topic-oriented approach well before they began migration to DITA. They began practicing the task-oriented writing while they’ve been using unstructured FrameMaker, without any DITA in place. Once their writers adopted the principles, learning how to implement them in DITA wasn’t a big challenge.

In the previous post, I wrote that making your content reusable is a design task in the first place. You would need to build an information architecture that enables reusability, regardless of a content standard or tool you use.

It also applies to writing. You would need to write in a way that makes your content more usable and useful for your content consumers. This is where the major learning curve is.

Yes, it’s true that you would still need to learn the DITA content model. Good news is that there are ways to make learning easier:

  • There are authoring tools, such as Fonto or Content Mapper, that hide the complexity of the content model and let you author in DITA without knowing much about DITA elements.

  • Lightweight DITA which contains only about 40 elements (as opposed to 600+ elements in standard DITA) could be a good option for beginners who want to start with something simple and easy-to-understand before they move to a full-scale DITA.

  • Bigger teams can create their own subset of only those DITA elements that they would actually use.

And remember about the reward that you are getting! DITA not only lets you create and deliver your content faster. It creates a new value for your customers by enabling them to get what they want easier and quicker.

You cannot use DITA without specialization


Specialization is a mechanism that allows you to create your own information types, elements, and attributes. You probably heard an opinion that DITA wasn’t meant to be used out-of-the-box, and the existing information types serve just as a basis for creating your own information types.

Specialization is definitely a powerful feature, it’s not a must to do it to benefit from DITA. DITAToo DITA CMS has hundreds of users around the world, including international corporations, but I can recall only a few cases when creating a specialization was really justified from day one:

  • In one case, we were building a solution for an aircraft builder. The solution had to be compliant with ATA2300 (an XML standard for flight operations), so we’ve created a DITA specialization that mimicked ATA2300 features in DITA.

  • In another case, the customer had a very strict content model for troubleshooting topics. A regular task couldn’t be used so we had to create a specialization.

  • The customer was creating training content in DITA and had a dozen of different types of learning topics whose structure was specific for their industry. Plus, they needed a rich semantics to enable automated processing of the training materials.

We can think about a lot of benefits that specialization may bring to you, like richer semantics, stricter content models, etc., but the investment isn’t always justified. Additionally, in many cases, what you might really need is a special visualization of certain elements, but not altering the content model itself. For example, if you want a certain DITA element to appear in your authoring tool with a label reflecting its semantics, you might be able to do it by configuring the authoring environment.

Authoring in DITA is like writing a code


More precisely, it’s been true a decade ago when XML editors were not mature enough and left technical writers alone with the hundreds of DITA elements and hard choices on which element to use in a given context.

Today, even full-blown XML editors, such as Oxygen and structured FrameMaker, provide a better guidance to writers. There are authoring tools intended for non-technical writers that let them create DITA without knowing anything about DITA. In our days, one can write in DITA without even suspecting that there’s DITA under the hood. Here’s an example of what authoring DITA in MS Word looks like.

Customization of output formats in DITA is complicated

True (but there’s good news, read below).

Typically, customization of output formats requires a modification of DITA Open Toolkit (DTA OT) stylesheets, which means XSLT coding. However, recently, alternative solutions become to emerge. Latest versions of Oxygen, for example, include an ability to set up the formatting of your PDF output using CSS. Also, there’s a tool called MiramoPDF that provide an easy-to-use user interface that lets you set up the layout and formatting of PDFs in a visual manner. Watch how MiramoPDF works with DITAToo in this short video.

Migration of the legacy content to DITA is hard and expensive

It might be true depending on the current state of your content, but the same applies to non-DITA solutions as well.

Just like with the DITA learning curve and making content reusable, conversion of the legacy content to DITA is a design task in the first place. If your legacy content, regardless of its current format, isn’t topic-oriented and wasn’t written with reusability in mind, wrapping it “as is” into DITA elements won’t bring any value.

The technical part of the conversion (when your content gets the DITA markup) should be preceded by reworking your content to make it conceptually fit the DITA paradigm. This includes standardizing the structure and language in the first place. This can be done while you are still using unstructured content formats and tools.

Then the technical part won’t take too long. A few years ago, as part of implementation of DITAToo DITA CMS in two large organizations, we were involved into the conversion part of the implementation. In both cases, the companies invested into teaching their writers the principles of minimalism, information typing, and topic-oriented approach. Although they both used unstructured FrameMaker, their documentation conceptually looked as if it were DITA. And although they both had many thousands of legacy content pages to be converted, the technical conversion was very fast, painless, and required only a minimum clean up.

17 views0 comments

Recent Posts

See All


bottom of page