Confessions of a Born-Again XML/DITA Evangelist – No. 1, I See the Light

A little background, from the mid-1990s to the early-2000s, I did a lot of work in SGML/XML for a large publisher of science books and journals. Since then, I've changed jobs a couple of times, and while I continued to do documentation, until very recently, it didn't involve content markup.

Fast forward to about three years ago, our telecommunications company was looking to DITA to help with our documentation issues. I think my first exposure to DITA was one of those half-day training seminars. Because of my background, I probably knew more about the subject going in than 90% of the people there, and for me anyway, what was being covered in half a day could just as easily have been done in a hour. At least, we got lunch.

Soon after, we started having DITA meetings. I could tell we weren't moving very fast on it, when one of the project leaders did a presentation about how she had converted her glutton-free muffin recipes to DITA topics. It's surprising how infrequently gluten-free muffins come up in a telecommunications context. 

Because I had documents to get out, I was able to skip most of these meetings. I knew I could be up speed quickly once we had a plan in place. About the time I had the DITA training, I also had some minimalism training, and I'm sure the two melded together for me to a certain degree. I knew that our customers did not read documentation to learn about the technology, they read it because they want to do something with the technology, i.e., tasks.

I knew that applying this philosophy to our documents would make them better for customers, regardless of whether we ever used DITA or not. In practice, this meant focusing on the tasks. If there was conceptual information related to the task, how much was necessary to accomplish it. Maybe some of it needed to be minimized so that the user can get to what they are trying to do more quickly. If the task was too long, maybe it needed to be broken into two simpler ones. Possibly, there was info buried in the task that needed to be a prerequisite before the user even starts. While this is not DITA, taking care of these things upfront would surely make the conversion to DITA more smooth. 

About a year ago, DITA was finally starting to gather steam at our company, which of course meant another half day DITA training. Woohoo, free lunch again. This time we were supposed to bring a document we had worked on to see how DITA could be applied to it. I picked a document about a new GPS feature, that provided better performance than the previous one.

I chose this document for a number of reasons. It was pretty short only about 12 pages, so it would be relatively easy to look at in a classroom. It only had one task, but I had put a lot of work into it to make sure that it was good. I'd had a fairly long lead time on the document, so I'd put a lot of effort into reorganizing and clarifying the rest of the document. Finally, since I'd spent so much time with it, I knew the content backwards and forwards, so I could find my way around super easy.

As expected, the DITA training was pretty basic. For our purposes, we were not using generic topics, just:

• task – How to do something
• concept – What something is
• reference – Information you need to look up

Going in, I could see the value the structure of the task model provided. Having to split everything else up into either concepts or references seemed a bit unwieldy to me. Still, I went in with an open mind. During the class, one of the exercises was to take our document and break it into tasks, concepts, and reference topics. We only had about 10 minutes, so it really had to be broad brush strokes. This is a task. This is a concept. This is a reference. This is another concept and so on.

I wasn't too worried about the tasks. There was only the one. The rest of the document was good shape. I just needed to put it into the proper concept and reference topic buckets. The document was in great shape, or so I thought.  I found a couple of topics that were very short and didn't say much.  One  related to a concept earlier that was also a bit spare. The two should be combined. The other concept didn't relate to anything else. I needed to go back to my engineer and do one of two things. Either flesh it out into something better or get rid of it.

The part of DITA that I found unwieldy in a 10-minute exercise helped me see issues that I had missed on my own. DITA shown down on me in all of its glory, and I could see the light. Okay, maybe that's a bit of a reach, but it made me realize the power of all the DITA topic models not just the one I thought most important.

Hopefully, you weren't offended by the mildly religious overtone I used just now, but I thought it justified. Keeping in that vein, next, we'll look at coding tasks as the Creators intended.