Home » blog » Mary Connor's blog

UA2009: Leveraging DITA-based tools

Posted April 6th, 2009 by Mary Connor

Another central message of the Software User Assistance 2009 conference was that DITA (created and donated by IBM) offers a useful open-source standard for structuring and managing documentation, perhaps more for its tool support than for its inherent merits. Several presenters who had issues with its information typing nevertheless used it because of tool support.

The panel on "Creating Help with DITA" described how the year-old DITA Help Subcommittee, chaired by Tony Self, seeks to integrate DITA-authored Help systems and software applications using context-sensitivity, to make it a practical platform for context Help. Today, DITA Open Toolkit can produce basic content in some Help formats (Eclipse Help, HTML Help, XHTML) and others, with advanced tinkering: simple “WebHelp”, context-sensitive Help (Eclipse and CHM), AIR Help. Typical DITA editors include Arbortext, XMetaL, FrameMaker, DITA CMS Tools, Serna; Help tools that output DITA include WebWorks ePublisher, Author-it, Adobe TCS, and RoboHelp Packager for AIR Help. Improvements for context-sensitive help are slated for DITA 1.3.

The big news for me was the maturity of the DITA Open Toolkit (OT) and its free Windows GUI, WinANT. The OT transforms DITA content into RTF, PDF, XHTML, and Windows Help (CHM), and more is possible through extensions (plug-ins). Tony Self wrote WinANT to put a Windows interface on the OT transformations, replacing command lines and “manual” build and ditaval files. It remembers settings and is aware of plug-ins, and its installation automates the OT install as well. WinANT wraps all of the power of ANT in a convenient GUI. WinANT nicely packages “skins” (settings for output formats), and more are being created and donated to the open source community. Given that customizing all of the outputs in XSL amounts to CSS tweaking, it's well within the capability of many tech writers to handle, and the price is compelling. And if someone writes an OT plug-in to output the emerging Help 3 standard from Microsoft, I think the future could be very DITA indeed.

Medtronics is delivering help via DITA and Eclipse (also open source), which is a development platform of extensible frameworks, tools, and runtimes for building, deploying, and managing software; it uses documentation plug-ins to provide content in HTML, with integrated search and indexing. It's for applications developed in Eclipse, but it can run standalone. Their help_data.xml defines which TOCs are visible; the DITA maps provide frameworks for defining system navigation, and individual maps are building blocks. A top-down construction makes links to topics and subordinate maps from the master TOC; with navrefs, the parent ditamap references the child. A bottom-up construction uses anchors to create insertion points in the master TOC for nav elements defined by the target; with anchors, the child ditamap references the parent. The base Eclipse UA platform and all documentation plug-ins install with the application and are managed using the Eclipse updater; incremental updates (which let you update individual files without replacing entire set) are possible, but it's risky!

Resources:

Mary Connor's blog | login or register to post comments | printer friendly version