Can DITA train writers? Or does it require too much programming?

DITA for writers (content creators)

I just did a search on for books for beginning technical writers and also to investigate what books are being written for our profession and for others wanting to start in our profession. I came across a book called Writing Software Documentation: A Task-Oriented Approach that suggests three categories for writing:

  • writing to teach (for eager learners)
  • writing to guide (for reluctant users of the product)
  • writing to provide a reference (for experts who need only occasional support)

I immediately saw a connection to the three content types that DITA prescribes:

  • concepts to teach understanding
  • tasks to guide performance
  • reference to offer facts or lists of information

Because writers have to immediately place the information they want to record into one of these three types of information, they are being trained on how to write in a task-oriented, performance-based manner, via DITA. I am especially interested in this “training” for wiki authors and talked about the idea at our recent presentation at the Central Texas DITA User Group meeting.

DITA for publishers (formatters)

Recently a few techpubs bloggers have been talking about DITA and its weaknesses, such as a lack of online help outputs, and how difficult it can be technically if you don’t already have a staff with pseudo-programming skills. Gordon Mclean writes “DITA is not the answer” and I think the question he is trying to answer is, “what is a single-sourcing tool we can use in our environment (which includes Technical Communications, Training, Pre-Sales and Marketing) with our current resources?” Instead of DITA, it looks like he’ll go with Author-it.

Since I just this past year moved from BMC, which is still moving to DITA, to a small techpubs group that uses Author-it, I can understand his reasoning and agree with his business case assessment. The toolchain for DITA is very nearly there, but often a CMS-based approach has too much overhead for small companies. It can be cost overkill when you have few topics to contain.

Scott Nesbitt followed up with his post, “DITA’s not THE answer for single sourcing.” I think he’s spot on with the analysis “it’s difficult to get good PDF or online help from DITA without extensively customizing XSL stylesheets or passing DITA source files through tools like FrameMaker, Flare, or WebWorks.” One of his commenters said something about consultants smelling blood in the water, yikes. In other words, I think he meant that XML consultants knew how much customization would be desired and can have a feeding frenzy on the potential work possibilities. My guess is that the people who have been around XML for years know that there are still basic needs for output, and their experiences have shown them that nothing that is structured is an “out of the box” experience. So much of the success depends on your content to begin with.

I’ve found the same conclusions about the output in my experience. When you dig into single sourcing, be it with DITA or another tool (Madcap Flare, Author-it, FrameMaker, RoboHelp, and the Adobe Technical Communication Suite) the real business-case killer seems to still be, where can I get pretty PDFs that are formatted just as I like them? With DITA, one answer is to go get the Mekon FrameMaker plug-in for the DITA Open Toolkit. No XSLT-FO knowledge required.

People love their tools to get their pretty PDFs or sleek online help systems. Plus, so many of the employers out there have a lot of content that looks pretty nice already in a specific tool. The legacy documentation may be one reason why hasn’t DITA helped our industry get away from tool love. Tech writers and their employers fall in love with tools. I’m not saying Gordon or Scott are tool lovers, but certainly some people they’re hiring will be. There is probably also an element of “if it ain’t broke, don’t fix it.”

DITA for all?

Sarah O’Keefe has a thought-provoking analogy in her comments on her post signed “DITA Dissident.” The analogy is that creating desserts using a frozen pie crust is one method of getting results. If a pretty PDF is your ultimate dessert, then for some, DITA is a bag of flour, meaning you’d better be a skilled baker if you’re going to use it for the best pie (PDF) ever. For others, DITA is a frozen pie crust that makes a perfectly good cherry pie (PDF) or apple pie (plain HTML) or chocolate creme pie (Eclipse help). Although isn’t the filling the content and the pie crust the DITA map?

Their conversation first started with Eliot Kimber discussing DITA’s use for narrative documents. Alan Porter talks about DITA use for narrative writing as well, but in a different line of thought in his post, Is DITA Just a Story?

All the posts I’ve linked to are enjoyable for me to read and to point to and to think about. I’ve read it before, and I’ll say it again, I believe along with others that DITA has the potential to transform our industry. Just last night I said to the San Antonio STC group, today we all speak HTML tags pretty fluently. In ten years, will we all speak DITA tags just as fluently? “I wrote the shortdesc according to the guidelines and it works for the topic, but I am not sure if my conref target is going to be there every time. I guess I should rewrite the concept topic.” Heed the warnings and experiences of others before making the leap to topic-oriented single-sourcing or your expectations and those of your customers may not be met.


  • February 13, 2008 - 7:58 am | Permalink

    I firmly believe that DITA is the way forward. And you are correct in your assessment of my post, and we will have our own obstacles to overcome.

    However we will be using DITA as the guidelines for how we create our topics (as far as we can).

    Thankfully the “pretty PDFs” argument isn’t really one we are prone to here, it really is about the technical requirements (IN and OUT) of a single source system, and the implicit cost of DITA.

    If a vendor was currently offering a DITA specific tool, even if the outputs were a bit naff, at reasonable cost (which includes configuration and setup) then we probably would’ve gone with that. At present it’s simply a matter of money, unfortunately.

  • Kai
    February 13, 2008 - 8:41 am | Permalink

    DITA or not, I can wholeheartedly recommend Barker’s book (first link above). Of all the books I’ve looked at and the half dozen or so I’ve read, it’s the most comprehensive and the most useful (to READ, as opposed to look up stuff…)

    Beyond the three forms of task-oriented software documentation, he discusses process (though in less detail than Hackos’s Information Development) and tools (balancing print and online, with a bias towards print).

  • February 13, 2008 - 1:20 pm | Permalink

    I think one of DITA’s main strengths is its absence of “pretty” and “sleek.” It has helped me focus on content that is “relevant” and “useful.” When all you have at the time of writing is words and their semantic markups, you get down to some serious writing.

  • February 14, 2008 - 11:12 am | Permalink

    Hi Anne

    This is an excellent and informative site.

    I am an ICT person who’s moving into info design and working on my XML and DITA.

    I’m writing for help with an important point that you spelled out very nicely. Generating decent controllable PDF fro DITA maps? Do you know of any “affordable way.” Do we really have to spend days on writing XSL param elements to get to control the output appearance?

    Thank you in advance if you considered responding to my query. And would be very interesting to discuss further issues on structured authoring.

  • February 14, 2008 - 12:46 pm | Permalink

    Thanks, all for your comments.

    Mike, your comment reminds me that even if the writers themselves are “over” the pretty formatting requirements and glad to be freed of formatting tedium, many writers still have business requirements from their client or employer that will dictate the “prettiness” guidelines. I agree with your sentiment, though! 🙂

    Khaled, thanks for reading and commenting! One “affordable” path for decent PDF output (if you have already invested in a FrameMaker license and nice templates) is the FrameMaker Adapter plug-in as a free download with the DITA Open ToolKit. I edited the post above with a link to That plug-in could be a “poor man’s” print engine. It’s what Jen Linton and Kylene Bruski used to get the nice book output for the Introduction to DITA book. That’s the only idea for a solution that I have for you, does anyone else have suggestions?

  • Pingback:   Musings on structured, topic-oriented authoring by Communications from DMN

  • February 19, 2008 - 4:52 am | Permalink

    I’ve not come across any other ‘nice’ solutions for DITA. That’s one of the barriers for me and many others I believe.. it also goes hand in hand with Mike’s comments though.

    The concentration on content is the major plus for me of single sourcing (I’d rather my writers were writing than increasing line spacing or tweak fonts).

    Although recent developments with me may see me swing back round to DITA, so if I find anything I’ll be posting it, don’t worry.

  • Leave a Reply