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