AODC day 1: An Update on DITA Features, Tools and Best Practices

This week I’m at AODC 2010: The Australasian Online Documentation and Content conference. We’re in Darwin, in the “top end” of Australia. Crocs and docs, what more can you ask for! This post is my summary of one of the sessions at the conference. The post is derived from my notes taken during the presentation. All the credit goes to Tony Self, the presenter. All the mistakes and omissions are my own.

After a busy, informative and fun-filled morning on Wednesday, we broke for lunch. Then Tony Self presented the first afternoon session, called “An Update on DITA Features, Tools, and Best Practices”.

Here’s a photo of Tony. I took it on Thursday morning when he was presenting another session. (I thought I’d better mention that, because he’s sure to notice that he’s wearing his Thursday shirt!)

AODC day 1: An Update on DITA

AODC day 1: An Update on DITA

Tony’s talk covered these topics:

  • An overview of DITA: authoring, content management, publishing tools and the DITA Open Toolkit.
  • A preview of the features in DITA 1.2.
  • The usefulness of specialisation and constraints.
  • DITA as used in various help-authoring tools (affectionately known as HATs).
  • Delivery options for content authored in DITA.

Introduction to DITA

Here are my key takeaways from this part of Tony’s session:

  • DITA is an OASIS standard for a form of XML.
  • DITA is a semantic markup language. There are no presentational elements. This enforces the separation of content from form.
  • When working with DITA, you use a suite of tools rather than a single tool. So for example, you may use an authoring tool for DITA, a separate publishing tool for DITA, another tool for reviewing content, and so on.

Some examples of authoring tools:

  • Arbortext
  • FrameMaker
  • XMetal
  • XXE (XMLmind XML Editor)
  • Serna
  • DITA Storm
  • oXygen

Interestingly, the DITA Open Toolkit is not on the list. The toolkit does not offer an authoring tool.

A hint: Because DITA is a standard, you can use the authoring tools interchangeably. The content is stored in exactly the same format.

Some CMSes are DITA aware:

  • Xdocs can use XMetal, XXE or oXygen
  • DITAworks
  • Ixiasoft DITA CMS
  • SDL Trisoft
  • Vasont
  • Siberlogic Sibersafe

Author-it is not on the list, because it can’t manage DITA content.

Other DITA tools:

  • XMetal Reviewer (an addon to XMetal)
  • Leximation DITA-FMx (a FrameMaker plugin)
  • Content Mapper for Information Mapping

Publishing or rendering tools:

  • MadCap Flare (Flare is not an authoring tool. You can import your DITA content into Flare and then output it into another format such as HTML.)
  • RoboHelp (As above, RoboHelp is not an authoring tool.)
  • Antenna House
  • XMLmind DITA Converter (ditac)
  • DITA Open Toolkit
  • WebWorks ePublisher
  • WinANT Echidna (Tony created this tool.)
  • Arbortext Publishing Engine

Pricing varies considerably. Some tools are free and opensource. Others are commercial and quite expensive.

DITA working with help authoring tools

These are some of the points Tony covered around DITA and HATs:

  • None of the common authoring tools are DITA editors.
  • Some are good DITA publishing tools (in particular, Tony mentioned Flare an RoboHelp).
  • WebWorks ePublisher supports DITA content.
  • Author-it allows you to export your content into DITA format. Note that it exports generic DITA content, not the full semantic markup.
  • With RoboHelp 8, you can import DITA content.
  • Flare 5 supports the import and export of DITA content. It does not support a round trip.

Delivering DITA content

DITA Open Toolkit can convert DITA to:

  • HTML Help (CHM files)
  • Eclipse Help — Tony gave us a quick demo of an Eclipse Help help system. He was running an Eclipse standalone web server from his own machine.

Commercial tools can convert DITA to WebHelp, AIR Help, ePub (eBook format) and many others.

There also plugins for the DITA Open Toolkit, dubbed OT plugins, that can produce:

  • Simple WebHelp
  • Context-sensitive help (Eclipse Help and CHM i.e. HTML Help)
  • AIR Help
  • eBook content

Increasing demand for different help formats

Tony pointed out that more and more user assistance is being delivered on “unusual” media such as phones, tablets, GPS displays, eBooks and augmented reality goggles. One of the beauties of DITA is that the separation of content from representation makes it easier to support a multitude of output media.

Tony’s verdict: Is DITA ready for us to produce professional online help?

If you’re looking for tri-pane help output such as HTML, HTML Help and Eclipse Help, you can do that with the OT.

If you want professional-looking output, you can do that with some work on the CSS style sheets

If you need context sensitivity, you can do that too with a bit of extra work.

But DITA is not quite ready for more sophisticated features such as popups and dropdowns.

DITA 1.2

In this part of the talk, Tony went into the new features of DITA 1.2. I didn’t take detailed notes here. Tony has a lot of information and I’m sure he’d be delighted to pass it on.

One of the bits I found interesting was that there’s been some criticism of DITA 1.2. Some people say DITA is becoming more and more flexible (“sloppy”) and therefore less and less useful, in that you can now add new types of <div> to the DITA “task” topic type. When you upgrade to DITA 1.2, your task topics will automatically become “sloppy”. If you like, you can “constrain” them to make them more strict.

Also pretty cool in DITA 1.2: The new “subjectScheme” ditamap element supports facets, a concept discussed in Matthew Ellison’s earlier session on search. (I’ve blogged about Matthew’s session.)

The DITA 1.2 standard has not yet been officially released. Even so, some tools support it already:

  • Open Toolkit 1.5
  • oXygen

Choosing a tool

Tony gave us some points to consider when choosing a DITA authoring tool:

  • The tool should be as compliant as possible i.e. it should support the current DITA standard.
  • The tool should support the round trip, so that you can open DITA content, work on it and then save it as DITA.
  • You need a tool that supports specialisation, so that you can add your own topic types.
  • It’s good to have a tool that is as open as possible, so that it is extensible and interoperable.

My conclusion

Thank you Tony for a useful update on the current state of affairs in DITA world. In particular, Tony has given us some great information on the tools available. For me, as someone who does not use DITA but is interested in the technology and its aims, it’s really useful to get a quick blast of information in this way.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 14 May 2010, in AODC, open standards, technical writing, xml and tagged , , , , . Bookmark the permalink. 3 Comments.

  1. Any info on opensource dita authoring tools? Or tools that support mac 🙂

    • Syntext have an open source, cross-platform editor called Serna. (They also have a commerical version of the same application.) There are other DITA open source projects, some of which have authoring components. I’m thinking in particular of the DITA Open Platform. There are also some free-for-personal-use commercial authoring tools, mostly Java-based, such as XMLmind XML Editor.

  1. Pingback: AODC Day 3: Introduction to DITA Conditional Publishing « ffeathers — a technical writer’s blog

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

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: