Experts in Information Management Solutions and Services

Optimized integration of documentation with Eclipse/RCP applications

Alexej Spas, instinctools GmbH

November 2009

2

Agenda

Background

Eclipse Specifics

Demo

Q & A

3

Background

4

Typical SW documentation deliverables:

Printed documentation materials (manuals, references etc.)

Application help

Context sensitive help

Documentation materials that should be published online (Online help)

Training materials

Reference documentation (API docs and s.o.)

... other documents

Most of these documents have quite a high potential for partial

content reuse.

5

Traditional Documentation Toolset

6

Challenges we are Facing in this Scenario are:

Dealing with different source formats and redundant content

Increasing Complexity of Documentation

Globalization & Localization

Shortening of Development Cycles

High Quality Expectations

Different Target Media

Need of Integration

Increasing Demand for Documentation Variants

Conclusion: Without consistent documentation methodology and

appropriate tool support there is very less chance to manage all

required deliverables efficiently

7

Solution

Methodology: Single source publishing allows:

same content to be used in different documents or in various

formats.

labor-intensive and expensive work of editing only to be carried out

once, on one source document.

further transformations to be performed mechanically, by

automated tools.

Implementation: XML/DITA:

DITA divides content into small, self-contained topics

DITA Topics can be reused in different deliverables.

Tools:

DITAworks as Authoring platform

DITAworks IDE tooling to enable efficient collaboration between

development and documentation teams

8

DITAworks Toolset

9

Advantages of DITAworks in This Scenario

Single-source publishing approach

Comfortable WYSIWYG editing

Generate different formats from single source

Minimize efforts spent on managing documentation variants

Increase content reuse and minimize amount of managed content

Minimize translation costs

Increase quality and consistency of documentation

Automatically build product documentation as part of product build

process

Content can be pulled from 3rd party systems

Content can be published to 3rd systems

10

Eclipse specifics

11

Additional Challenges in Eclipse RCP Scenario:

Organizing efficient collaboration between Dev team and Doc team

Continuous development: Detecting new undocumented places in

Source code

Support of all Eclipse Help features in Single Source environment (live

actions, cheat sheets and s.o.)

2 alternative ways of Help Context ID mappings

Componentization of documentation: Cross-plugin links in

documentation

Link validation

Direct Context Mapping Approach

UI Plug-In

PlatformUI.getWorkbench().

getHelpSystem().setHelp

(control, help_Context_ID)

Eclipse Help

System

Presents context-sensitive

help for context ID

Help Context ID

PlatformUI.getWorkbench().getHelpSystem()

.setHelp(dialog.getShell(),

IWorkbenchHelpContextIds.NEW_WIZARD);

Dynamic Context Mapping Approach

Source: http://www.eclipse.org/datatools/doc/20080520_DTP_Help-Helper.pdf

14

Mapping Strategies Compared

Direct context mapping approach

“+”:

Simple

“-”:

Context IDs hardcoded into source code

1:1 relationship between context IDs and contexts

Dynamic context mapping approach

“+”:

Context IDs in source code and in documentation are decoupled

Doc. team can freely assign Context IDs to any context (N:N)

“-”:

Requires more management

15

DITAworks: Extended Eclipse Help support

Highlights:

Specialized DITA types for support eclipse help and contexts

Support of live actions and cheat sheets

Cross-plugin links generation and validation

Support of dynamic context ID mapping (DTP approach)

Eclipse help specific validations

Tools for integration with development process. (Context IDs

management between development and documentation teams)

Plug-in for Eclipse IDE

ID synchronization wizards

16

Demo

17

Demo details and goals

Based on classical Eclipse “RCP Mail Template” example project

Create a documentation for our sample RCP application in form of:

Eclipse Help

PDF

Assign context help according to Dynamic Context Mapping Strategy

Demonstrate the work environments for Dev and Doc teams

Demonstrate the process

Eclipse Help Documentation Process

19

Step 1: setup infrastructure

2 workspaces for Dev and Doc teams

Shared projects (via VC) for content exchange

Different tooling:

Eclipse IDE + DITAworks IDE tools for Dev

DITAworks for Doc teams

Work infrastructure

/mail.rcp

/mail.doc

/mail.doc.sources

/mail.doc

/mail.doc.sources

/mail_Model

Version Control:

/mail.rcp

/mail.doc

/mail.doc.sources

/mail_Model

21

Step 2: Assign context IDs in code

Role: Developer

Tool: DITAworks IDE tooling

Find Java UI components

that require Help Context ID

Assign new Context IDs

using refactoring wizard.

22

Step 3: Export context IDs to shared project

Role: Developer

Tool: DITAworks IDE tooling

Run Export Wizard for

Context IDs

Describe exported IDs

(optional)

Store Context IDs to

shared help source project

23

Step 4: Assimilate context IDs and document

Role: Doc team

Tool: DITAworks

Open or Import exported

Context IDs

Document: Assign existing

topics. Write new topics.

Assign Context

definitions to help plugin

24

Step 5: Publish Eclipse help documentation

Role: Doc team

Tool: DITAworks

Setup publishing

configuration for Eclipse

help plug-in

Run publishing process

Share results.

25

Step 6: Integrate help into application

Role: Developer

Tool: Eclipse IDE

Include Documentation

bundles into application.

Include org.eclipse.help.*

bundles

Build & Run

Press F1 on one of the

views in sample app

26

Step 7: Generate other formats

Role: Doc team

Tool: DITAworks

Setup publishing

configuration for Eclipse

help plug-in

Run publishing process

Press F1 on one of the

views in sample app

27

Summary

DITAworks addresses most of the challenges in the area of RCP

application documentation as a ready out-of-the-box product

DITAworks enables single-source approach to the development of

documentation under Eclipse

DITAworks can be easily integrated with other Eclipse based tools

DITAworks provides IDE tooling to optimize collaboration

DITAworks pays special attention to support of Eclipse help format

DITAworks is also a good starting point for custom solutions dealing

with structured document generation

28

Q & A

29

Sophienstr. 17

D-70178 Stuttgart

phone: +49 (0) 711 - 99 33 85 90fax: +49 (0) 711 - 99 33 85 99e-mail: info@instinctools.cominternet: www.instinctools.com

New Ideas in Information Management

Management Team in Germany, Software Lab near shore (Belarus)

Successfully serving premium customers like Daimler, Hubert Burda Media, Garant,

EnBW and SMEs

Proven management processes and reliable project delivery infrastructure

Member of tekom, Eclipse Foundation

30

*instinctools GmbH delivers Information Management solutions on Java technology

since 2001, on Eclipse since 2007

MD

Management

Technical

Management

R & D

Management

Product

Development

Project

Management

Customer

Support

Project

Services

Partner

Sales

Consulting

Implementation

Partners

Germany (Stuttgart)

Belarus (Grodno)

Eclipse Application Design and Implementation Services

Eclipse Application Maintenance and Support

Tools for Technical Documentation (single source strategies)

About *instinctools