DITAworks Integartion With RCP


Published on

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.

  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

DITAworks Integartion With RCP

  1. 1. Experts in Information Management Solutions and Services Optimized integration of documentation with Eclipse/RCP applications Alexej Spas, instinctools GmbH November 2009
  2. 2. Agenda  Background  Eclipse Specifics  Demo  Q&A 2
  3. 3. Background 3
  4. 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. 5. Traditional Documentation Toolset 5
  6. 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. 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. 8. DITAworks Toolset 8
  9. 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. 10. Eclipse specifics 10
  11. 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. 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. 13. Dynamic Context Mapping Approach Source: http://www.eclipse.org/datatools/doc/20080520_DTP_Help-Helper.pdf
  14. 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. 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. 16. Demo 16
  17. 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. 18. Eclipse Help Documentation Process
  19. 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. 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. 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. 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. 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. 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. 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. 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. 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. 28. Q&A 28
  29. 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. 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