This article discusses the main challenges that a documentation team faces when it decides to use DITA as a source format for Eclipse Help documentation. It also explains how DITAworks documentation tool plans to address these challenges.

About Eclipse Help

The Eclipse Platform includes its own help system based on an XML table of contents referencing HTML files.  This is a standard way to document Eclipse-based software products.

But eclipse help format is not reduced to usages only inside of Eclipse platform. It is available as standalone server solution and can be used for providing ANY help content via Web server. Eclipse help system provides such important functions like navigation through TOCs, search, indexing, bookmarking and s.o.

When Eclipse help is used for documentation of Eclipse-based software, it allows much more sophisticated mechanisms for context-dependent help definitions like: search expressions, contexts, so called cheat sheets and s.o.

Additionally, due to component-oriented architecture of Eclipse, Eclipse help is structured in form of plugins that can be independently deployed and interlinked. This enables creation of scalable documentation that fits to complex product configurations.

Eclipse Help and DITA

DITA as single-source architecture opens a promising approach for maintaining all your documentation in single format. Eclipse help as one of the publishing formats can address needs of context dependent application help as well as generic online help.

DITA Open Toolkit provides a way to transform DITA maps and topics into Eclipse help plugins, but these possibilities are quite limited. Namely DITA OT will generate a TOC file and set of HTML topics linked to source map, but it does not address following important specifics of Eclipse Help:

• Definition of contexts (used for context-dependent help)
• Interlinking topics between several Eclipse help plugins
• Definition of search phrases
• Definition of cheat sheets
• Tuning of plug-in contents (Manifest properties, amount of TOCs, indexes, contexts and s.o.)
• Some other advanced features of eclipse help.

These limitations are hindering adoption of Eclipse help as publishing output format for DITA content.  They need to be addressed if we want to use the full capability of Eclipse help system and this issue can be seen as a current challenge for DITA-oriented tooling.

(more…)