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.
Get new posts delivered straight to your inbox.
I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here. You can also contact me with questions.