Confessions of a DITA Virgin

Dear DITA Virgin,

I was so relieved to read your article last week. I too, am a DITA virgin. I’ve been in meetings where the term was used (our company is considering moving to DITA) but I really had no idea what it was. In context, it sounded like DITA was a system for organizing and reusing written content. Is that about right?

I even went to Wikipedia to look up what it has to say about DITA. And here’s what I found:

“The Darwin Information Typing Architecture or Document Information Typing Architecture (DITA) is an XMLdata model for authoring and publishing.”

That didn’t help at all! “An XML model for authoring and publishing?” Huh? So, what’s XML? And what does it mean that it’s a “model?” As soon as I stuck my toe in the water, I felt like I was going to drown. So, I hopped out of that pool completely and haven’t dared return – until I saw your article. Please help!

Drowning in DITA Ignorance


Dear DIDI,

First, there’s no reason to be embarrassed. There are plenty of topics I know nothing about. But there are places to learn about everything. And I’m here to help you and other DITA virgins learn the basics about this one topic.

So, let’s start at the beginning – with the goal. There are probably many goals of DITA, but we’ll focus today on the most obvious one: Content Reuse. Wouldn’t it be nice if our content was chunked into smaller “sections” or “blocks” of text, rather than creating large, monolithic chapters or books?

For instance, instead of writing everything over, or even copying and pasting from other documents, someone about to teach a training class on a piece of software could press a button and produce a student guide and a training guide. After the class, back at their desk, a user of that software could print a user manual or pull up online help from many of the same materials.

Naturally, the materials would be arranged differently, without the quizzes and background information found in the classroom books, formatted mainly as step-by-step instructions to make it easy for them to use as quick reference. And, when they get stuck, the user support person they’ve called presses a button which goes back to that same set of “blocks” and puts together just the pieces they need to provide answers to the struggling user. Wouldn’t that be nice? It would be.

So, how could we go about that? Well, we could write little sections of text that can be assembled in different ways to meet the needs of different readers. We could store all those little sections of text (let’s just call them blocks from here on) someplace and carefully label them so we’d know “this is a list about installation steps” or “this is background information about when to use this feature of the software” and so on.

We’d have to have a way to “mark up” those pieces of text to label them (and that’s where “markup language” comes in). And we’d need something to read all those labels to find the pieces and put them together in the order each reader needs them to be for their desired publication. Let’s imagine for a second that we could write everything in plain, unformatted text (no bold, italics, heading 1, 2, or 3 styles, no indentation, no space before or after paragraphs, no margins – no formatting at all).

Then, the program that puts all those little building blocks of text together could also read tags to “bold this when it’s in a user guide, but underline it when it’s in a student manual for training.” All that tagging? Yeah, that’s DITA at it’s most simple. What I just described is how DITA “marks up” text for reuse.

There are other markup languages with different uses. Of course, we have to know which tags to use. We need a way to mark them up (for instance, can you actually do that in Word or do you need a different tool). And there needs to be a way to pull all those building blocks together into the various documents we need. But those are topics for future posts. I hope this helps!

–The DITA Virgin