Upload
wildwildleha
View
461
Download
1
Tags:
Embed Size (px)
DESCRIPTION
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.
Citation preview
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
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: [email protected]: 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