The time has arrived for standard for user assistance to be developed and agreed upon. The benefits are many, and include providing certainty and a way forward. The current status quo is a situation where there is a 10 year old standard for Microsoft Windows-based Help systems (HTML Help), and no standard approach to (or even a defacto standard for) user assistance for Web-based applications.
Different players in the Help Authoring Tool arena have different vested interests. With the right approach, an XML-based standard for user assistance could satisfy most of these interests, which include the following.
It is also obvious that an enormous amount of effort is required to devise an XML standard, and agreement from all parties is also a difficult objective. Finding the path of least resistance could be the best approach. If the devised standard was developed under the auspices of the W3C, there would be a better chance of industry-wide acceptance, although working within an OASIS framework might provide similar credibility.
There are three components of a Help platform:
The authoring tool should simplify the markup process, and assist with API integration.
| Help Technology | Markup Language | Viewer | API |
|---|---|---|---|
| WinHelp | RTF | WinHelp or WinHlp32 | WinHelp API |
| HTML Help | HTML | HH | HTML Help API |
| "WebHelp" | HTML | Web Browser | JavaScript |
| JavaHelp | HTML | JavaHelp Viewer | JavaHelp API |
| Vista Help | AML | Vista Help Pane | Vista Help API |
Help systems, being hypertext systems, are by nature topic-based. (Hypertext theory holds that there are just two basic elements in a document: topics - or nodes - and links.) Other types of content within the broader field of user assistance (which encompasses standalone Help systems, field descriptions, tool tips and embedded Help content), also fit well into the topic-based paradigm. It would therefore seem that a topic-based architecture of a User Assistance XML standard would be the logical approach.
There already exits a topic-based XML standard for documentation: DITA. DITA's purposes are much broader than just user assistance, but DITA can be used for user assistance. So why not use DITA as a User Assistance XML? The short answer would seem to be that DITA is too complex. So why not simplify DITA? A cut-down version of DITA is likely to satisfy most of the markup requirements for user assistance, and does not require the construction of a new standard from the ground up. Specifying a simplified DITA, or compact DITA, or DITA UA, would seem to be the path of least resistance.
A compact DITA would make the process of developing viewer applications a lot cheaper than a whole of DITA viewer.
One of the ambitions of a Help environment should be cross-platform compatibility. Once a Help file is created, it should be able to be displayed on a Windows PC with Firefox, on a Mac with Safari, or on a Linux PC with Lynx. While a Web browser may be a suitable platform for UA XML delivery to support Web-based applications, it may be unrealistic to expect browsers to support the context-sensitive and display functionality required of a Help system for a desktop application. For this reason, specialised UA XML viewing programs are desirable. If a user assistance XML standard is developed, the task of creating a standalone compliant UA Viewer will be relatively easy. Again, working within an accepted standards framework means that Microsoft may choose to develop a UA XML viewer for Windows, a HAT vendor may choose to develop an alternative UA XML viewer, and a third party may choose to develop another alternative viewer in Java for Mac, Unix or Windows delivery. The author of the content should not need to worry about what viewer might be used; separation of content from delivery - an XML principle - will hold true.
The functionality of viewer software should include the following.
It would be advantageous to have a community-developed toolkit to support the creation of viewer software, and have that toolkit freely available. The toolkit might include XSL transformers and CSS files for display and filtering of content and navigation files.
Implementation of context-sensitive Help is simplified through an Application Programming Interface, where common programming routines and functions are bundled for easy re-use. The main purposes of a UA API are to:
The existing WinHelp and HTML Help API structures could be maintained for UA XML APIs, with very little effort. Some programming effort would be required, of course, to develop APIs for each potential delivery platform. For example, an API would be required for Help delivered via a UA XML viewer in the Windows environment, or Help delivered via a browser in a Linux environment, etc.
A UA XML standard, despite best intentions, will be a technical standard. A document written to that standard may well be technically valid and well-formed, but that won't make it a good piece of communication. It may also not be semantically correct, in that inappropriate elements may have been used. For these reasons, it is desirable that a best practice guide be written for the standard, to provide documentation of the correct use of the elements, along with suggestions and examples of typical types of content.
In the 1990s, Microsoft produced a document named the Help Author's Guide, which filled the same role as a UA XML best practice guide but for the WinHelp environment.