JoAnn Hackos, Comtech Services, Inc.

In mid-June, I spoke at an impromptu session sponsored by OASIS in China. Several of the individuals in attendance were representatives of Chinese government standards bodies. My role was to describe the OASIS DITA standard, since we hope that Chinese companies will adopt it for the development of technical information. I was surprised in the question and answer session when one of the representatives, apparently a professor from a technical discipline at Beijing University asserted that DITA was too complex.

The OASIS DITA Technical Committee, responsible for the development of the DITA standard, has recently been grappling with the assertion that DITA is too complex. We have discussed in the Committee many possible avenues we might pursue to reduce complexity or to make DITA easier to learn.

However, the question from the standards representative strikes me as typical of someone who approaches DITA by downloading the DITA Document Type Definitions (DTDs) and the DITA Open Toolkit and expecting to learn the DITA standard by “hacking around.” Sometimes, but not always, the same individual may download the DITA specification as a PDF, HTML, or CHM collection and try reading it, usually with little success.

Another unfortunate course of action is going to Google and searching on DITA. My search in Safari came up with DITA eyewear first. Luckily, second entry was the official DITA website, dita.xml.org but most of the other references were of little value. Does anyone still think that a blind Google search of the Internet is the way to learn something besides the latest scandals?

These observations lead me to developing a short article, which describes my personal view of the best ways to get started with DITA.

Let’s start by explaining that the DITA specification, especially the 2010 1.2 specification, is not intended for end-users and is not a learning tool. Earlier versions (1.0 and 1.1) had content appropriate for end-users, especially technical communicators, but for the 1.2 specification, committee members decided that the audience for the specification should be developers. With that in mind, the main body of the specification was rewritten to focus on the technical architecture so that the development community, including product developers and inhouse technical experts, could better understand the details. Some of the end-user related content moved to the subsections on technical communication and learning and training.

Consequently, if you think that you can simply pick up and read the specification to get started with understanding DITA, you are probably mistaken unless you’re already an expert in XML architecture and want to devote a lot of time to getting started.

So what is an information-development manager, an author, a budding information architect, or anyone else who wants to investigate what DITA is, what its benefits are, and what it takes to become proficient to do?

1. Attend a workshop, especially one that provides hands-on work with basic DITA.

As many of you already know, Comtech offers beginning and advanced DITA workshops, as well as the 4 ½ -day DITA Boot Camp. Other groups offer workshops that provide introductory training in the standard.

2. Listen to webinars on DITA, although they are less useful than workshops because you don’t get hands-on experience.

Webinars are available through product vendors and consultants, as well as through organizations like the Society for Technical Communication andCIDM. Many are free; some have small fees to attend and receive a recording. Many webinars are archived for later listening.

3. Buy a book about DITA. Comtech has had our Introduction to DITA available since 2006. It’s now in its second edition (2011).

Introduction to DITA explains concepts and includes a series of lessons from writing topics and assembling maps to applying conditions and content references to publishing. Since our book first came out, we have seen several other books appear. You’ll find a recent list at the DITA Awareness Group in Linked In.

4. Download a temporary copy of a DITA editor or find one of the free ones online and start trying to create topics and maps.

Most of the companies that sell DITA editors offer free but limited downloads. Some don’t limit the number of times you can renew.

5. Go to the official website of the OASIS DITA community,http://dita.xml.org.

Look first at the Knowledge Base tab for basic information. Find the feature articles written by the DITA Adoption Technical Committee members. There is a wealth of information here for those just getting started.

6. Join a local user group. You’ll find them in most major metropolitan areas in the US. List and contact information is available athttp://dita.xml.org/book/dita-user-groups.

7. Read articles offered by official publications like CIDM and STC.

These articles have been peer-reviewed and contain unbiased and accurate content. Many articles provide accounts of the experience of others who have implemented the DITA standard.

8. Use the version of the DITA Open Toolkit that comes with many of the editors to produce sample output.

But remember that the style developed for the PDF version of the Open Toolkit is pretty awful and many new elements are not styled at all. The DITA Open Toolkit is a volunteer effort, mostly by programmers who clearly are not visual design experts. You may eventually need to pay for help to develop a design that is acceptable to your organization. Note that it also took someone many hours or even years to become proficient in designing styles in FrameMaker. Designing a stable style in MS Word is impossible.

Getting started with DITA should imply being successful. You would not, or at least I hope not, decide to learn how to program in C++ by downloading a compiler and experimenting. It would be good to know how the language is organized, how it is supposed to function, what it does effectively, and what it does not do effectively. You would probably buy a book, take a class, listen to many YouTube videos, but I doubt you’d expect to pick up the entire language just by hacking around.

DITA is not another tool like FrameMaker or MS Word. It is a standard and a specification that is supported more or less effectively by open-source and commercial tools. As a standard, DITA is a way of working, a way of thinking about the structure of information. It’s greatest benefits come from understanding the architecture and deciding if you’re ready to make the leap into a new authoring and publishing environment. It’s definitely worth the effort because the benefits to productivity and quality are huge.

Dr. JoAnn Hackos is the CIDM Director.