Back to DITA?

I’ve mentioned DITA a few times on this blog, and my DITA is not the answer post is still attracting attention. As I’ve said, I think the DITA standard is an excellent one for software documentation and the DITA movement is slowly catching up to the hype. I’ve never given up on DITA and had always planned to use it as the basis for the next stage of our content development, and as it happens the switch to a full DITA/CMS based solution may be closer than I had anticipated.

We have been considering how best to publish up to date information in keeping with patches and minor releases, and if we can tidy up and publish useful information from our internal Wikis and support system. The nature of the product we work with means there are a lot of different usage patterns, not all of which we would document as they fall outwith typical (common) usage.

So, how to publish formal product documentation, in-line with three versions of the product, in PDF for ‘printed’ manuals, JavaHelp to be added to our product, and HTML to be published to a live website alongside other technical content (ideally maintained in the same system as the product documentation). Storing the content as XML chunks also allows us to further re-use the content programmatically (which can be tied into our product in a smarter, dynamic, fashion).

The obvious answer is single source using DITA to structure the content, storing the content as XML to give us the greatest potential avenues for re-use. Nothing particularly startling there I know, but it’s a switch from the direction we had been considering. So I’ve been catching up on what’s new in DITA-land and have to admit I’m a little disappointed.

We already have FrameMaker and Webworks in-house, although both are a couple of versions old, and thinking we might keep using those applications I’ve been hunting about to see if I can find a solution that offers a coherent, end-to-end, story. There are several CMS solutions which require an editor, editing solutions which require a CMS, and a few products that straddle both CMS and editing but then require publishing engines.

I understand that it would take a collaboration between vendors to be able to offer a simple, seamless solution

In addition to that there does seem to be a tendency for any DITA focused solution to remain the remit of the overly technical. Don’t get me wrong, I’m quite happy delving into XML code, hacking elements, or running command line scripts to get things done. But surely I shouldn’t have to resort such things? Now, I’m sure there are many vendors who will tell me that I don’t need to worry, but I’ve seen several demos and all of them miss a part of the FULL story.

Come on then vendors, stick your necks out. If you are a CMS provider, then recommend an editor. If you sell editing software then talk nice to a CMS vendor and start promoting each other (yeah Adobe, I’m looking at you!).

And yes, I’ll happily admit that maybe I’m just not looking closely enough. If only there was some sort of technical community website that I could join, perhaps with a group or two on DITA? That’d be great.

Ohhh wait. There is! (not the most subtle plug in the world, was it? I think the new Content Wrangler communities could be a big hit, do check them out).

Have a got the wrong end of the stick, are there really gaps in the market in this area at present or is it just my imagination? I guess I’ll be running a fair few evaluations over the coming few weeks and, of course, I’ll post my thoughts and findings here.


  1. Tony, I have looked at DocBook but DITA matches our requirements better, and based on a content audit the migration of our legacy content matches the DITA topic structure perfectly.

    Having read your post, the solution you offer, whilst cheap, is as you say “lo-tech”. My point about a vendor led solution, based on a standard, means we get a nice experience using the process, but aren’t locked in to any proprietary formats.

    In particular, I DO NOT WANT to spend time ‘tweaking’ code for layout. Single source is supposed to remove all of that!

    To be honest, the underlying standard isn’t really the issue, I could build a lo-tech solution based on DITA as well but it still boils down to having to hack and fudge things.

    To me, single source solutions are all about relieving my team of the burden of hacking, allowing them to concentrate on creating content.

  2. We are piloting the DocZone solution for DITA CMS, XML authoring and translation workflows soon. While we are awaiting their software-as-a-service implementation, we needed to continue developing some content in Arbortext. We have to edit hrefs that Arbortext Editor inserts to remove the complete file paths (we want them to be relative, not absolute). Then we have the problem of getting the PDF and HTML output we want — haven’t gotten into how to get AE to do that yet.
    I have also investigated importing DITA content created outside of FrameMaker into FM 8 and it works pretty well, so you can style the page layout and tweak the typography in it just like any other FM documents. See You can build an FM .book from a ditamap and then print that to PDF with all the bells and whistles. But for HTML you have to install a plug-in to FM to run the Open Toolkit, which is not very friendly. I have turned to Hyperwrite WinANT by Tony Self for my HTML output.
    So while there is progress, so far it’s been kind of half-hearted from the XML authoring application vendors. We hope that DocZone will give us a seamless authoring-to-publishing capability (Xopus is included for writing XML and TopLeaf is integrated for PDF output). But in that case you are using their CMS as a service, so you have to decide if that works for your situation.
    It is a mixed environment — I think the next year or so will bring some really good products to market in the DITA space, but meanwhile there’s work to do, so we just find the tools we can and get the job done.

  3. Dorothy, thanks for all those details, very good of you to share.

    You touch on something I agree with, namely that the products aren’t quite there yet but are probably close enough that the effort required to get a solution in place is worthwhile.

    I’ll look into DocZone.

  4. Great you are choosing a single-source system to manage your documentation.

    Based on the comments thread I would like to add some stuff for thought:

    “based on a content audit the migration of our legacy content matches the DITA topic structure perfectly.

    This statement is valid for.. whole the companies in the world. DITA uses a very flexible architecure and can map anything… However the mappping for your company does not exist yet. Experts will have to do the wrok ($$$). My advice: ask your partner how much it will cost to do the mapping and how long it will take…

    “I DO NOT WANT to spend time ‘tweaking’ code for layout.”
    Makes sense 🙂 However, both DITA and Docbook use stylesheets to render the final output. So these stylesheets will have to be created and/or tweaked.

    You may also be interested in this article that compares Docbook and DITA:

    Please don’t take me wrong. I am sure you have good reasons to go for DITA. I just wanted to bring a neutral input to the discussion.

    Good luck with your migration to DITA!

  5. Fabrice, I always welcome discussion on these topics. That’s why I post them!

    I will summarise why we are going with DITA in a separate post, and it certainly looks like I need to get a little deeper into this before we go any further.

    Thanks for the info, very useful.

Comments are closed.

%d bloggers like this: