Alan HouserPrincipal Consultant and Trainer

Tel: 412-363-3481arh@groupwellesley.comwww.groupwellesley.com

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 Houserarh@groupwellesley.com

Group Wellesley, Inc.933 Wellesley RoadPittsburgh, PA 15206USA412-363-3481www.groupwellesley.com