Using DITA for Online Help


Published on

Presented by Alan Houser at Documentation and Training West, May 6-9, 2008

DITA provides an end-to-end architecture for authoring, managing, and publishing topic-oriented technical information. DITA may appear to be an ideal solution for authoring and maintaining online help systems. However, the DITA specification does not directly accommodate many of the customary and expected features provided by conventional help authoring tools. Learn how you can use DITA today to deliver online help, and learn what the DITA Technical Committee is doing to make DITA more directly usable for online help in the future.

Attendees will learn the following:

* How features of the DITA architecture map to the structure of conventional online help systems
* Why DITA can provide an ideal solution for authoring, maintaining, and delivering online help
* Current issues and limitations when using DITA for online help
* Common features of help authoring tools and how they map to (or don’t map to) DITA
* Approaches for maintaining and delivering DITA-based context-sensitive help

Published in: Business, Education
  • Be the first to comment

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

No notes for slide

Using DITA for Online Help

  1. 1. <ul><li>Using DITA for Online Help </li></ul>Alan Houser Principal Consultant and Trainer Tel: 412-363-3481 [email_address] Group Wellesley, Inc.
  2. 2. Presentation Summary <ul><li>An unfinished story… </li></ul>
  3. 3. About Me <ul><li>Consultant and trainer in publishing tools and technologies </li></ul><ul><li>Member OASIS DITA Technical Committee </li></ul><ul><li>Member OASIS DITA Help Subcommittee </li></ul><ul><li>Society for Technical Communication, Liaison to the World Wide Web Consortium (W3C) </li></ul>
  4. 4. Overview of DITA design <ul><li>Roots of DITA: minimalist approach </li></ul>
  5. 5. DITA and Online Help: The Possibilities <ul><li>In many ways, DITA looks like an architecture for creating help systems: </li></ul><ul><li>Topic-oriented architecture </li></ul><ul><li>Maps to define sets of topics for delivery </li></ul><ul><li>Separation of content and presentation </li></ul><ul><li>Support for conditional builds; reusable components </li></ul>
  6. 6. DITA Information Types <ul><li>Generic topic type </li></ul><ul><li>Task, concept, reference specialized types </li></ul><ul><li>Can create your own information types through a process called specialization . </li></ul><ul><li>Define DITA deliverables through DITA Maps </li></ul><ul><li>Maintain related topics in an external map file </li></ul>
  7. 7. DITA Domains <ul><li>Inline markup to identify special words and phrases for highlighting or processing </li></ul><ul><li>Highlighting domain for presentation markup: <b>, <i>, <tt>, <u> </li></ul><ul><li>Software, programming, user interface domains for semantic markup: <cmdname>, <varname>, <apiname>, <codeblock>, <uicontrol>, <menucascade> </li></ul>
  8. 8. Other DITA features <ul><li>Content re-use at topic and fragment level. </li></ul><ul><li>Metadata-based content filtering. </li></ul><ul><li>Related topics specification and management. </li></ul>
  9. 9. Design Goals of DITA <ul><li>Standards-based, end-to-end architecture for creating, managing, and delivering topic-oriented user assistance. </li></ul><ul><li>Highly customizable </li></ul><ul><li>Universal source file interoperability and exchange </li></ul><ul><li>Content reuse </li></ul>
  10. 10. Design Goals of DITA (2) <ul><li>Content filtering </li></ul><ul><li>Separation of information units (topics) and collections (maps) </li></ul><ul><li>Minimalist information architecture </li></ul><ul><li>Separation of content and format </li></ul>
  11. 11. Expectations of Online Help Features <ul><li>Output formats: WinHelp, HTML Help, Web Help, Adobe AIR </li></ul><ul><li>Navigation, search </li></ul><ul><li>Behaviors: Pop-up windows, drop-down regions </li></ul><ul><li>Tri-pane user interface </li></ul><ul><li>Context sensitivity </li></ul><ul><li>Many of these expectations are not in alignment with DITA design goals. </li></ul>
  12. 12. Example: HTML Help
  13. 13. Example: Customized Help Engine
  14. 14. Example: Customized (AIR-based) Help Viewer
  15. 15. Example: Customized (AIR-based) Help Viewer
  16. 16. Example: MS Windows Vista Help
  17. 17. Generating Output from DITA <ul><li>Output formats supported by the DITA Open Toolkit include: </li></ul><ul><li>XHTML, PDF, HTML Help (CHM), Eclipse Help, Java Help </li></ul>
  18. 18. DITA versus HATs <ul><li>Help authoring tools (HATs) are designed to provide features and support workflows specifically for online help. </li></ul><ul><li>DITA is a standards-based architecture supported by open-source processing tools (e.g., the DITA Open Toolkit). Tools support is emerging. A high degree of customization is possible/required. </li></ul>
  19. 19. Protocols for Context-Sensitive Online Help <ul><li>There is no standard way to communication between an application and a help system. </li></ul><ul><li>An application may identify a topic by an integer, a string, a URL, a topic title, or some other piece of information. </li></ul><ul><li>What if a DITA topic collection is used to support multiple applications with multiple context-sensitivity protocols? </li></ul>
  20. 20. Approaches to DITA for Help <ul><li>The legacy approach: </li></ul><ul><li>Use DITA Open Toolkit to generate “HTMLHelp” target. </li></ul><ul><li>‘ htmlhelp2’ plug-in, available from dita-users Yahoo group files area. Generates *.alias and *.map file. <topic> <title>Getting started</title> <prolog> <resourceid appname=&quot;WindowsHelpId&quot; id=“31415&quot;/> </prolog> ... </topic> </li></ul>
  21. 21. Approaches to DITA for Help (2) <ul><li>The “Do it all yourself” approach: </li></ul><ul><li>Customize context hooks based on <resourceid> and/or <othermeta> elements. </li></ul><ul><li>Customize DITA Open Toolkit to generate necessary intermediate files for your programming language and development environment. </li></ul>
  22. 22. Approaches to DITA for Help (3) <ul><li>The “Punt” approach: </li></ul><ul><li>Use HTML or PDF outputs for your application help. Don’t provide topic-specific context sensitivity, drop-downs, pop-ups, or any other conventional online help features. </li></ul>
  23. 23. Approaches to DITA for Help (4) <ul><li>The “Hybrid” approach: </li></ul><ul><li>Import DITA-authored topics into a conventional help authoring tool via an intermediate format. </li></ul><ul><li>Examples: Import XHTML topics into HAT </li></ul><ul><li>Adobe Technical Communication Suite: Import FrameMaker content into RoboHelp 7 </li></ul>
  24. 24. Major Issues for Help Authoring with DITA <ul><li>Commonly expected behaviors in online help systems. </li></ul><ul><li>Conflicts with goal of separating content and format. </li></ul><ul><li>Behaviors (and their specification) may vary with help viewer. </li></ul><ul><li>Storage, presentation, and maintenance of context-sensitive “hooks”. </li></ul><ul><li>Format of hooks may vary by programming language, development environment, and delivery format. </li></ul>
  25. 25. OASIS DITA Help Subcommittee <ul><li>An official OASIS-sanctioned subcommittee of the DITA Technical Committee. </li></ul><ul><li>Goals include: </li></ul><ul><li>Create design for authoring help systems using DITA </li></ul><ul><li>Recommend design and best practices for supporting context-sensitivity and other expected behaviors </li></ul><ul><li>Establish guidelines for using DITA for online help and user assistance </li></ul>
  26. 26. Conclusions <ul><li>If traditional context-sensitive online help is your primary target, DITA may not provide the most efficient approach. </li></ul><ul><li>If you have chosen DITA because it meets your organization’s requirements, traditional context-sensitive help is feasible. </li></ul><ul><li>DITA’s standards-based, open-source processing tools make nearly any customization possible (although not necessarily easy). </li></ul><ul><li>The technologies and answers are evolving. </li></ul>
  27. 27. Resources <ul><li>DITA for Help – </li></ul><ul><li>OASIS DITA Help Subcommittee – </li></ul><ul><li>HAT Feature Matrix – </li></ul><ul><li>WinANT tool for generating DITA output – </li></ul>
  28. 28. Resources <ul><li>OASIS public DITA Home Page: committees/tc_home.php?wg_abbrev=dita </li></ul><ul><li>OASIS DITA information site </li></ul><ul><li>DITA Open Toolkit </li></ul><ul><li>IBM Task Modeler </li></ul>
  29. 29. Contact Us! <ul><li>We hope you enjoyed this presentation. Please feel free to contact us: </li></ul><ul><li>Alan Houser [email_address] Group Wellesley, Inc. 933 Wellesley Road Pittsburgh, PA 15206 USA 412-363-3481 </li></ul>