Technical writers, DITA, wikis and hippies

Today I attended a DITA training course presented by Tactics Consulting and Tony Self of Hyperwrite. It is always a pleasure to listen to Tony. He has such a charming way of conveying information that could otherwise be considered dry and boring by some 😉

I thoroughly enjoyed the wry humour that inevitably happens when technical writers find themselves in the same room together. Tony told us how Darwin and the finches got together with the hippies to produce an XML documentation standard just for us.

The course was centred around structured authoring methodologies with DITA as the tool. My primary interest is the feasibility of having DITA as a supported output from a wiki. Confluence, to be specific.

Clever people have spent thousands of hours devising DITA, and will continue to do so. How awesome if our product documentation could hook into this cleverness for purposes like these:

  • Delivering content in different media such as PDF, Postscript, HTML, RTF.
  • Converting content to other authoring environments, including other wikis. This would be useful for our customers who have products like Bamboo or JIRA but use a different wiki. Or for customers who use Confluence to write their own product documentation which they need to pass on to their customers in turn.
  • Localisation and reducing costs of translation e.g. by converting from DITA to XLIFF as an information exchange mechanism between us and the people who translate the documentation. Translation of our documentation is going to become more and more of a requirement.
  • The ability to respond quickly to customers who request the documentation in some format that we don’t know about or support but for which someone has already created the DITA transformation.

At first, the wiki to DITA conversion would use only a subset of DITA capabilities. I’d suggest we don’t try to constrain the wiki authors by enforcing too much structure on the content. If we did that, we would run the risk of spoiling the flexible collaboration and quick authoring that are the heart of a wiki.

But we could still have enough typing to make the process worthwhile. We could map semantics which are naturally in the wiki markup to the corresponding DITA elements. The wiki could offer a more structured option for those who want to use it. One way might be for authors to tag a page as a concept, task or reference via labels or other metadata. Then we could perform an intelligent mapping of the information chunks within the page, falling back to the least typed content when necessary e.g. a concept.

It would not be a trivial task. I wouldn’t think of DITA as the primary authoring tool or even as the backend storage mechanism for the wiki content. Not yet, anyway. Instead, how awesome if Confluence could export compliant DITA, to a level of detail and even to a specialisation determined by the information architect.

These were the thoughts that wandered through my head while Tony guided us through the joys of WYSIOO (What You See Is One Option) and tools that are not ideal. He used a different word for that phrase 😉

Thank you to Tactics for a great day, to Tony for his charm and skill and knowledge, and to the other tech writers on the course for … well, just for being tech writers. It was great to be with a bunch of people who know that it really matters where you put your semi-colon and whether the XSD allows for a stem sentence.

(People are working on DITA and wikis already. See my posts tagged ‘DITA’ and Anne Gentle’s too.)


About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 24 November 2008, in atlassian, Confluence, open standards, wiki, xml and tagged , , , . Bookmark the permalink. 6 Comments.

  1. Andrew Lui (Atlassian)

    I attended this course as well, and thoroughly enjoyed it. Thanks to Tony for such an engaging and in-depth presentation.

  2. Hi, I agree it won’t work to constrain the contributors to using a schema; DITA is unfriendly enough already for those of us who get paid to author with it &-).

    There’s a new Mylyn wikitext-to-DITA project, see

    XML editors are still so primitive. Dreamweaver is almost there, but not quite!

  3. Hallo Dee and Andrew
    Wow Dee, thank you for the link to the Mylyn wikitext-to-DITA project. Very interesting! I’ll have a good read when time allows. Thanks also for your comment. Awesome feedback both.

  4. Thanks for the write-up, and for your insight, Sarah. I accidentally came up with a word for a DITA-based Wiki yesterday. It’s “diki”. If it catches on, I’m going to claim credit!

  5. Heh “diki”, that’s awesome Tony!

  6. Thanks, Sarah. A couple of us here were just musing about wiki-to-DITA today.

    > I’d suggest we don’t try to constrain the wiki authors by enforcing too much structure on the content.

    Yes–if you bend Confluence too much to make it better for DITA authoring, be careful not to end up with something that’s good for neither wiki nor DITA.

    I’m happily using Confluence for my early outlining, drafting and brainstorming. When the time comes to move it to our authoring environment I’d be happy with a ‘good enough’ export that preserves the basic structure and formatting.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: