Blog Archives

AODC day 2: A Beginner’s Introduction to DITA

This week I’m at AODC 2010, the Australasian Online Documentation and Content conference. We’re in Darwin, in the “top end” of Australia. In this session, though, we’re dealing with wolves, not crocodiles. 😉 This post is my summary of one of the sessions at the conference. The post is derived from my notes taken during the presentation. All the credit goes to Suchi Govindarajan, the presenter. All the mistakes and omissions are my own.

AODC day 2: Who's Afraid of the DITA Wolf?

AODC day 2: Who's Afraid of the DITA Wolf?

Suchi Govindarajan had a catchy title for her talk: “Who’s Afraid of the DITA Wolf?”

At the beginning of the session, Tony Self handed out some pretty coloured squares of paper to each of us. Intriguing! The coloured paper was soon explained. Suchi started by telling us a story about origami. Of course, this set me wondering what this origami had to do with DITA! Good start.

Suchi said that she found it really amusing that she was here talking about DITA. About a year ago, she was totally baffled about DITA. Then she attended a course given by Tony Self. Now she’s here to give a beginner’s view of DITA.

She led us through the steps to make an origami pelican, following the step-by-step instructions in her slide show. I’m hopeless at things like origami, but nevertheless I managed to follow the steps (with help from my neighbour) and make something resembling a bird.

AODC day 2: Who's Afraid of the DITA Wolf?

AODC day 2: Who's Afraid of the DITA Wolf?

Next, Suchi showed us some text about origami: an explanation of the theory of origami, an investigation of the maths behind origami, and other theoretical scripts about origami. She explained how different texts have different purposes, and not all are step by step guides, and not all are useful to a beginner.

DITA introductory material

What did Suchi’s origami demonstration have to do with DITA? She showed us some introductory material to DITA, pointing out how the texts were full of words and terms that a beginner would not understand.

So Suchi has written her own definition of DITA, specifically for beginners:

DITA is a standard for technical documents that’s designed to be used with XML. It comes with some free publishing tools.

We already know DITA

As technical writers, we already know much about DITA. Suchi showed us how a number of the concerns DITA addresses, and many of the terms used, have been part of standard technical writing for years. Examples are content re-use, topic-based authoring and content models.

DITA has an elegant way of handling these standard technical writing concepts.

How to learn DITA

Before you start, you need only a very little:

  • An understanding of XML elements and attributes — just know what they are.
  • An idea of the three DITA topic types: concept, task and reference.

Then get a DITA editor, such as XMLMind or XMetal. Suchi usees and recommends XMLMind. You can download a free edition for personal use.

From that point on, the editor helps you to learn the quirks of DITA. Suchi gave us a quick demo of XMLMind, showing us how the editor enforces the DITA rules while you are writing your content.

At this point, you don’t need to know about the complex features of DITA like specialisation, customisation, inheritance, etc. You also don’t need to know about the DITA “topic” topic.

You also don’t need to know about XML rules, validation and well-formedness. The editor will take care of that. You can learn about it later, once you’ve got through the beginner stage.

Because DITA tags are semantic, it’s easy to guess what each element means judging by its name.

Start with a good example. Download and analyse some sample topics. Suchi gave us a link to the DITA OT user guide as a good set of sample topics.

She also recommends this tutorial: DITA for Solo Writers, the Lone-DITA guide.

The real wolves of DITA

DITA is not a wolf, says Suchi. 🙂 On the other hand, the DITA OpenToolkit is horrible. Don’t use it!

Another wolf is ourselves. If you start with a closed mind, it’s hard to learn what DITA offers.

Going further

Once you’ve done some editing and created some content, you can start looking at publishing your DITA content. Here’s where you would install the DITA OpenToolkit, but don’t use it. Instead, install one of the other tools that use the toolkit:

  • WinANT
  • XMLMind DITA Converter
  • Other publishing tools you already own

My conclusion

Thank you to Suchi for a calm, reassuring introduction to DITA. Suchi had the audience in the palm of her hand. Her speaking style is relaxed and charming. She told us about a one-day DITA workshop called “DITA in a Day”, that she has created. It sounds well worth attending!

%d bloggers like this: