I recently had my first experience with authoring task-oriented content in DITA. Now, I’ve been around DITA since early days, but I haven’t worked as an information developer since late SGML / early XML days (that was in the last century for you kids out there). I am very familiar with component content and writing for reuse. But I did have some eye-opening experiences when I started creating task-based content in DITA while contributing content and reviewing our easyDITA User Guide.
Warning … and a confession: I’ve had no formal training in DITA authoring. (Why? I’m not a technical writer by trade anymore – I’m a CEO. But hey – even a CEO can use our product!)
That said, I am pretty familiar with the main concepts behind DITA, and I’ve read a book or two on the subject, so I know enough to be dangerous. Plus I’ve used many DITA authoring tools, and I use ours everyday for creating documents for our business (including this blog post).
Without the formal training, getting the information architecture right for DITA tasks was a bit of trial and error – so kids, don’t try this at home (really, please go to a class or a boot camp session on DITA best practices). But it did give me insights that I’d love to share with you.
Our User Guide was written to be naturally re-purposed for our on-line context-sensitive help in MindTouch and as a series of How To posts on our support portal knowledge base. This meant that each task really had to stand on its own two feet. The structure of our User Guide is pretty much a master DITA concept for each functional area of the software (e.g. the easyDITA Editor), followed by a series of How To tasks that cover the operations of the software (e.g. How To Create a New DITA Topic). There are some supporting concepts as required, usually for defining some underlying DITA concepts (e.g. Topics and Maps).
I’d like to share some of the insights I gained from my first albeit naïve foray creating task-oriented content:
- Writing Tasks makes your content inherently more consistent. Well, maybe not at first, and certainly not without some effort and thought (ideally in the form of IA work before the content is written). But Tasks do lay bare the inconsistencies in your content. How? Let me count the ways:
- Titles. Those pesky titles; you’ll notice really quickly that you want them all to be in consistent Gerund-Object format (e.g. “Deleting Files”).
- Short Descriptions. They’ll start to bug you if they aren’t consistent, too.
- Commands. Like Task Titles, you’ll see a pattern develop in your commands – you want them to start with a Verb in the command form, and be as terse as possible.
- Software Features. Good DITA keeps formatting to a minimum. If the tasks are in a software User Guide, you’ll want to semantically tag references to what the user sees on the screen. Software controls and displays are the objects of your Commands and the Results in your Tasks. These include standard DITA elements like command names, menu cascades, file paths, messages and UI controls. Format these with your stylesheets for complete consistency.
- Tasks are leaner. Thinking in terms of commands, results, and examples keeps the conceptual gunk out of your tasks. I know mine could stand some improvement, but our manual is much leaner than the first version, which was not task-oriented.
- Tasks are modular. With tasks, we have much more natural reuse of our content between the context-sensitive help in our application, the User Guide, Knowledge Base, and Social Help system. We adopted MindTouch some months after the UG was rewritten as tasks, but the content naturally flowed into the new delivery format.
- Tasks are perfect for Contributed content. One of our earliest customers started using Tasks right away as the format for contributed content from their Software Engineer SMEs. They found with a few minutes of training on the Dos and Don’ts of Task authoring, any SME could start contributing content in Tasks. They now have about 25 SMEs contributing structured content as Tasks. Sure, the authors need to do some clean up, but it’s a far cry better than unstructured contribution.
Do you have any experiences to share about how authoring Tasks improved the quality of your writing? Please share them here.
Latest posts by Paul Wlodarczyk (see all)
- How to decide if DITA is right for you – and where to learn more - February 16, 2014
- Task-Oriented Info Dev for Agile Software Development - October 31, 2012
- The trouble with delivering product documentation in wikis – and some better alternatives - July 20, 2012