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.

Eclipse Help and documentation process

Another main challenge in the area of Eclipse help can be found in organization approach to documentation process. In tasks that require definition of context-sensitive help, authoring team needs to work closely together with software development teams. This is required because software developers need to integrate IDs of help topics and contexts inside of software UI code. Same IDs should be mapped to help content created by authoring team.

The documentation process and software development process very often have iterative nature. So the synchronization of IDs, which are defined in software code and in documentation itself, can become a serious quality issue.

Documentation management tools have to support documentation team in this process and provide efficient ways to automate this process. It needs to be ensured that all software UI components are assigned with the contextual help IDs and these IDs are linked to help content.

Contextual help mapping strategies

As there is a need for mapping between software UI elements and documentation contexts, let’s take a look on how this is actually done in Eclipse Help.

In most of the cases, two alternative strategies of ID mapping are used. These are:

1. Direct mapping. When context IDs of help content are placed “AS IS” in software code. This is the easiest approach, but it has a set of disadvantages e.g. this approach requires a lot of discipline in the issue of ID generation and mapping. In most of the cases, one of the teams (software development or documentation) will own the responsibility to generate unique IDs and to assign them. The other team will need to map those. This approach creates a lot of organizational overhead and does not provide needed flexibility.
2. Indirect mapping. In this approach, the software development and documentation teams can define their own context IDs independently.  Later on, these IDs are mapped to each other using a special mapping tool. This approach makes it possible to separate the processes of software development, documentation development and documentation mapping. It provides much greater flexibility in organizational aspects. Example of this approach can be seen here (DTP Approach to Eclipse Help mapping): http://www.eclipse.org/datatools/doc/20080310_DTP_Help-Helper.pdf

Advanced support of Eclipse Help in DITAworks

As DITAworks is an Eclipse-based tool, our product team decided to address challenges described above by the release of DITAworks 1.0. One of the objectives of this release is to make creation of Eclipse Help documentation in DITA as easy as possible.

The main features that will make this possible in DITAworks are described below.

Eclipse help DITA model

To define missing semantics and data structures that are needed for Eclipse Help features, we will create a new EclipseHelp DITA model (specialization). Model in DITAworks is a container for meta information that includes various elements like DITA infotypes, transformation styles, templates, editorial tools configurations and s.o.  It can be roughly compared to DITA Open Toolkit plug-in.

EclipseHelp model will include a set of specialized DITA infotypes:

• EclipseHelpPlugin - specialization of DITA map covering the specifics of Eclipse help plug-in descriptors
• EclipseHelpContext - specialization of DITA map that will be used to model context sensitive help contexts

Model will also define transformations for these infotypes, the set of visualization settings for map editor, preview templates, content validation rules and s.o.

Eclipse help model will also define an Eclipse Help project template that will make it easy for the user to start working with Eclipse Help projects.

Transformation styles will be adjusted to resolve cross plug-in links in Eclipse Help properly.

Mapping strategies in DITAworks

DITAworks will support both the strategies of ID mapping mentioned above: Direct and Indirect.

Indirect mapping strategy will be the recommended approach and it will follow the ideas described in DTP Approach to Eclipse Help mapping.

DITAworks will also provide a set of tools that will support software developers and documentation team members in the process of context ID mapping. These tools include:

1. Plugin for SW development Eclipse IDE that will support developers to generate and assign help contexts according to Indirect mapping approach. It will also detect UI elements that do not have help contexts assigned and then propose to generate context IDs for them.
2. Set of Import/Export actions that will enable the exchange of context IDs between software development and documentation teams.
3. Assignment plugin for documentation team. (out of scope for release 1.0)  It will provide the visual support in indirect assignment of generated UI context IDs to documentation context IDs. It will be possible to deploy this plugin directly into the documented Eclipse software and perform the assignment by browsing the documented UI and checking out available help content for it. In the case where content is not assigned, plugin will offer a set of available context IDs for the assignment or a possibility to add “TODO” for future.

Documentation process in DITAworks

To address the challenges described in “Eclipse Help and documentation process” section, DITAworks will support indirect mapping approach “out-of-the-box” when the development and documentation teams are working independently.

In the diagram below, we can see a sequence of actions that need to be performed for one documentation cycle/iteration:

The documentation process can start in parallel with the developers’ coding software components. The developers will use the plugins described in the previous section to automatically generate and assign context IDs to user interface elements. These IDs will be later used by the documentation team for assignment.

In the next step, the assigned IDs will be exported from IDE into the special mapping file and will be passed on to the documentation team (import to DITAworks). This is one of the possible ways to hand over the context IDs. Some alternatives can also be considered like the direct extraction of IDs from source code and s.o.

Next, documentation team documents software elements not documented yet and then maps already documented parts to incoming IDs. This mapping could be done directly in DITAworks or by using the special Assignment plugin.

Optionally, the assigned IDs can be back-synced to the Developer IDE.

In the last step, DITAworks generates a set of Eclipse help plugins from DITA source and ID mapping information. Eclipse help plugins are split into content plugins and context plugins. The content plugins contain topics and TOCs and the context plugins contain context assignments.

In the next development iteration, this process can start from the beginning with only difference being that the imported IDs will extend already existing IDs and documentation team will need to document only the newly added UI elements.

Tags: DITA, DITAWorks, Eclipse Help

This entry was posted on Monday, April 27th, 2009 at 16:52 by Alexej Spas and is filed under Coming soon, Features, Problems and Solutions. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.