The appeal of 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.
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.
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.
About Tom Johnson
I'm a technical writer based in the San Francisco Bay area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out simplifying complexity and API documentation for some deep dives into these topics. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates. You can also learn more about me or contact me.