Alan Houser Principal Consultant and Trainer Tel: 412-363-3481 [email protected] www.groupwellesley.com Using DITA for Online Help Group Wellesley, Inc.
Nov 07, 2014
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