Presentation form Nov 2009 Eclipse DemoCamp in Stuttgart. This presentation talks about how DITA can be used for efficient management of Eclipse help documentation with support of DITAworks. It also presents how DITAworks IDE tooling can help to optimize managemnt of Eclipse help context IDs and communication between development and documentation teams.

1. 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
2

3. Background
3

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.
4

5. Traditional Documentation Toolset
5

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
6

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
7

8. DITAworks Toolset
8

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
9

10. Eclipse specifics
10

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
11

12. Direct Context Mapping Approach
UI Plug-In Eclipse Help
System
PlatformUI.getWorkbench().
getHelpSystem().setHelp Presents context-sensitive
(control, help_Context_ID) help for context ID
Help Context ID
PlatformUI.getWorkbench().getHelpSystem()
.setHelp(dialog.getShell(),
IWorkbenchHelpContextIds.NEW_WIZARD);

13. 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
14

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
15

16. Demo
16

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
17

18. 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
19

20. Work infrastructure
Version Control:
/mail.rcp /mail.rcp /mail.doc
/mail.doc /mail.doc /mail.doc.sources
/mail.doc.sources /mail.doc.sources /mail_Model
/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.
21

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
22

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
23

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.
24

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
25

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
26

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
27

28. Q&A
28

29. New Ideas in Information Management
Sophienstr. 17
D-70178 Stuttgart
phone: +49 (0) 711 - 99 33 85 90
fax: +49 (0) 711 - 99 33 85 99
e-mail: info@instinctools.com
internet: www.instinctools.com
29

30. About *instinctools
 *instinctools GmbH delivers Information Management solutions on Java technology
since 2001, on Eclipse since 2007
Germany (Stuttgart)
 Eclipse Application Design and MD
Project
Partner
R&D Management
Implementation Services Management Management Customer Sales
Support
 Eclipse Application Maintenance and
Consulting
Support Implementation
Technical Product Partners
 Tools for Technical Documentation Management Development Project
Services
(single source strategies)
Belarus (Grodno)
 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