Gunthilde Sohn, instinctools GmbH
For professionally developed software and applications to be successful, proper documentation is one of the key factors. Documentation needs grow exponentially with new software releases and versions. To keep up with this growth in documentation needs and provide quality outputs within a reasonable time and with the least waste in resources, a synchronized approach with close collaboration between application and documentation teams is needed. In this article, we share a best practice on how to bring productivity to the documentation of Eclipse RCP applications.
Introduction: Eclipse Specifics
Eclipse provides its own subsystem for documentation: the Eclipse Help subsystem which expects documentation to be provided in Eclipse Help format and supports two ways of presentation:
1. In the “book” mode or “Infocenter” mode: Users can browse the documentation structure, search through the documentation, and browse the documentation index as shown in Figure 1.
2. As context-sensitive help: Users will get the appropriate help page depending on the application context (window).
We want to transform DITA documentation to Eclipse Help format and create a special Eclipse plug-in from it which can be distributed with an Eclipse RCP application. And we also want to create Eclipse context-sensitive help from the documentation.
For context-sensitive help, the main challenge lies in synchronization of IDs used in source code with context definitions, taking into account that IDs and documentation are created by different and often distributed teams.
We need a DITA-enabled authoring tool to create documentation content. We are using the DITAworks authoring platform but the same conceptual approach can also be extended to other authoring tools if they provide appropriate tools support.
The process of RCP documentation development will be split into two parts. The first part is done by RCP developers and the second part is done by the documentation development team. Both the workflows are interlinked to work like clockwork as shown in Figure 2.
For the first group of activities, DITAworks comes with a special Eclipse plug-in that can be installed on the RCP developers’ workstations. The second group of activities can all be done in an automated way in DITAworks. The tasks are explained further as follows.
1.1 Defining Contexts IDs in Eclipse RCP Source Code
Firstly, RCP developers need to assign unique context ID to UI controls. Each UI component can have one context ID. It will be possible later to link several related topics and provide a text description for each Context ID. Context ID assignments can be static or dynamic.
1.2 Delivering Context IDs Data to the Documentation Team
Then, RCP developers have to transfer a file with Context ID definitions to the documentation team. We suggest use of version control for sharing this file.
1.3 Creating Eclipse Help Plug-in in RCP Application
Next, RCP developers need to create an eclipse plug-in project in Eclipse IDE and link it from the target platform of the RCP application. This plug-in project will be used to exchange information between the development and the documentation teams. This plug-in project should be shared with the documentation team through the version control system.
2.1 Creating DITA Documentation
The documentation team needs to create DITA topics and maps for the final deliverables. This task can be done in parallel to the RCP development activities 1.1 – 1.3 as described above.
2.2 Creating a Specialized DITA Map for Editing Eclipse Help Context
Next, a specialized DITA map object for storing Eclipse Help context data should be created. It allows storing context data in DITA and using available tools and validation mechanisms.
2.3 Importing Context IDs Provided by RCP Development Team
The documentation team needs to import the Context IDs provided by the development team.
2.4 Defining Contexts
Then, the documentation team creates the context definition by using a map editor.
2.5 Publishing Documentation
Finally, DITA documentation can be published to the plug-in that was created by RCP developers in step 1.1. As a result, Eclipse Help is available for further use as needed.
This approach adds productivity to documentation development which in turn provides productivity to the whole Eclipse RCP product development. There is a smooth and synchronized workflow for documentation development that saves both time and costs.
To simplify and speed up help-related activities for RCP developers, DITAworks includes a special Eclipse plug-in that can be deployed to the RCP developers’ Eclipse environment. The Eclipse plug-in in DITAworks comes with an “Export Contexts to DITAworks” function. Merging with an existing context definition file is also supported by the plug-in.
DITAworks includes an EclipseHelpPluginMap specialization that can be used to create a specialized DITA map object and has inbuilt functionality for importing Context ID data. There is also support for file merging in case context IDs that have been imported earlier as well.