The appeal of DITA

by Tom Johnson on Jan 4, 2014
categories: dita

For about the past 6 months, I've been using Markdown syntax as a quick way to convert content to HTML and publish on Drupal, which is where we publish our help. But lately I've been feeling the pain of this process.

Markdown is a lightweight markup somewhat like a wiki syntax. Any time I needed to do something more, like prepare a collection of more than 5+ files to publish at once, with cross-references between them, it's been a chore using Markdown.

Additionally, we now need to push select help content into printable workbooks for training sessions (a requirement we didn't have before). I knew the Markdown method was only temporary. And it's time to say goodbye to Markdown.

As a pilot to a new solution, I'm trying out DITA. I've played around with DITA in the past, mostly out of curiosity. This past week I converted about 20 real help files to DITA, so I put my head in the books and really started learning it.

I can now understand why DITA has such a strong appeal and popularity. It's simply a cool way to author content. It's not so different from any other markup language, in that you simply put tags around content. But the idea of a markup language specific to technical writers' needs is awesome.

I fear I'm becoming a DITA follower. I recognize that this may require me to rethink some of my beliefs about the best practices with organizing content.

I'm not used to modularizing every sequence of steps into its own file, or eliminating most inline links except via relationship tables, or banishing h3 sections, but I'm willing to try it for a while and make a go at it. It doesn't seem sensible to use DITA without following standard practices with DITA content and organization.

I know I have a lot to learn, but I'm also a self-learner. DITA seems a lot easier than JavaScript programming (I'm not including the XSLT transformation part of DITA, obviously). And there are so many good books and resources online.

For example, here are 200 DITA related videos.

This book on Safari books is pretty good: DITA Best Practices, by Bellamy, Carey, and Schlodfeldt. Very clear.

There's Tony Self's DITA Style Guide.

And the DITA for the Impatient tutorial by Hussein Shafie.

Some books I haven't gotten to include DITA 101 by Rockley and Cooper, Practical DITA by Julio Vasquez, and DITA for Print by Leigh White, etc.

I'm currently working my way through Eliot Kimber's DITA for Practitioners.

There is also a tremendously helpful conference approaching for anyone who is interested in structured content. It's called Intelligent Content, and it's held right here in lovely San Jose, California.

Our biggest barrier to DITA adoption in the past has been connecting DITA to Drupal, so we'll also be experimenting with a script for that. I'm pretty optimistic about it right now.

In short, expect more posts about DITA from me in the upcoming months.