Help Documentation System Review

By Denny Schlesinger, President, Help Software, Inc.

The Importance of Documentation

I believe that the secret of the Macintosh revolution is based mainly of two things: an easy to learn, nonthreatening, graphics based interface, and consistency in applying that interface to each new Macintosh application. The one missing component--until now, that is--has been a way to create consistent on-line documentation.

Why didn’t Apple Computer provide documentation procedures as part of its otherwise excellent operating system? A source at Apple said that originally they thought that the Macintosh concept was so good that it would not require documentation. He also confessed that they are no longer that sure. The result is that--until now--the Macintosh lacked consistency in on-line documentation. Some software houses who do provide on-line documentation, are not consistent across their product line.

Indeed, it would seem a contradiction that easy to use, intuitive programs should require on-line documentation. The real the purpose of documentation is not limited to illustrating the common, intuitive and easy to use interface of Macintosh programs. Complete documentation covers a wide spectrum: the machine itself, its operating system, the application program, and how the program is used within the user’s organization. No single entity that has the capacity, the knowledge or the resources to produce complete documentation. Complete documentation is an incremental collection of information contained in hardware manuals, operating system manuals, application manuals and tutorials, corporate standard instruction manuals, corporate training programs, memos and other instructions. Documentation is used in many different ways: the developer has different needs than the user; the novice has different requirements than the power user; the new employee differs from his supervisor; production does things differently than the accounting or advertising departments.

To fill this wider scope, documentation must be modular: the information provided by the prime source must be editable at each new level of use to adapt it to that level’s needs. Considered in this new light, documentation becomes a useful and integral component of your product and of the whole Macintosh environment. Now documentation helps to transmit new and useful information at each level of use. Documentation changes from a costly add-on to a hot, new, useful and salable feature.

To achieve modularity, documentation needs a standard tool, available to all Macintosh developers and users. HDS, an off the shelf component, is similar in concept to the tool box in ROM. HDS provides consistency in documentation in the same way that Apple’s tool box provides consistency for the other parts of the Macintosh user interface. With consistent documentation, you save time, you save money and you produce a better and more useful product.

Fig. 1 The Help On-line Documentation System

What is HDS

HDS is a two part system: The Help Editor desk accessory creates the on-line documentation, and the Help desk accessory (the run-time) lets the end user access this documentation. Since Help is a desk accessory, it is independent of--and transparent to--the program that it documents. (See figure 1, the Help Editor Menu. )

The independence of the Help Documentation System makes it an ideal documentation tool for Macintosh applications and it can be used at every stage in the development and usage of a Macintosh program. A new layer of documentation can be added at each stage:

• Apple Computer can document the Macintosh hardware and the Systems software

• The developer can document the features of his application program

• The VAR can document the components added to the system

• The MIS manager can document how the package is used within his corporation

• The departmental manager can document how the package is used within the department

• The user can document how he goes about doing specific tasks

A new subset of the documentation can be created for specific purposes:

• A basic set with tutorials can be created for training new workers

• An advanced set documenting shortcuts can be created for power users

• A foreign set can be created for overseas offices

This is the first time that the basic documentation produced by the developer can be expanded, modified and made useful at every stage in the usage of a Macintosh application program. The Help Documentation System is an important step in the direction of creating customizable software.

Why on-line? First, very few computer users manage to keep the manual within handy reach. Second, when you release a new version of an application, you can easily revise the documentation to match, without the time and expense of printing a new hard copy user’s guide. The trend is catching on, notice the proliferation of Read-me-First documents being distributed with Macintosh programs. With the advent of hard disks and CD ROMs, on-line documentation is becoming the rule rather than the exception.

Who Is the HDS Package For?

HDS takes a lot of the work out of software documentation. It is self evident that consistency across applications is a mayor benefit for Macintosh users. The same benefit is realized by the consistency in documentation provided by HDS. Developers can rid themselves of a giant headache with HDS, leaving more time for code development.

With a few instructions, your program can call the Help desk accessory to provide context sensitive help and extended alert messages. Corporate Trainers and VARs can also make use of the HDS system for creating customized on-line instruction and training materials.

HDS provides the unprecedented opportunity to replace how to books with on-line manuals. The best place for help is right on the screen in front of the user. If this help is interactive with the program being used, so much the better. HDS provides both of these desired features. With the advent of CD ROM the space problem will be solved and on-line manuals will come into their own.

Some international companies translate the language interface for their software; others don’t. In providing software packages for the international market, it’s often better to leave key words and phrases in English and to provide explanations in the user’s native language. Since Help files have their own font (Cyrillic, Katakana, and so forth), the program interface can be written in English, and the documentation, in any other language.

Most people make notes and reminders to themselves. The most accessible place for these notes is with the rest of the information about the program you are using.

Design Criteria for HDS

The following criteria were agreed upon in the design of the Help Documentation System:

• HDS requires a well known and workable metaphor.

• HDS must follow the Macintosh user interface guidelines.

• The documentation for any program might be very large.

• Access must be quick, therefore, the path to any information must be short.

As a result, we selected the “well referenced book” metaphor and implemented equivalents for:

• Table of Contents

• Alphabetic Index

• Glossary

• Cross Referencing

• Visual Glossary

• List of Illustrations

• How to Use This Book

Then we extended the metaphor with concepts from the Macintosh User Interface Guidelines and Macintosh usage:

• Help for Menus

• Context Sensitive Help

• Extended Alerts

The access path to the documentation is through a multibranched, three level tree. The root node has 7 branches which correspond to the implementation of the “well referenced book” metaphor and its extensions. These 7 branches correspond to the seven access points to the documentation.

Fig. 2 The Table of Contents

Organizing your Documentation with HDS

There is an intrinsic structure imposed on your documentation by the “well referenced book” metaphor of HDS. Within this overall organization, you are free to create the structure that is most convenient for your documentation.

HDS documentation has two principal purposes or modes: The didactic mode, for teaching, is created and accessed with the Contents feature. The reference mode, for fast random access, uses all the other access features. (See figure 2, Table of Contents)

Table of Contents

The didactic part of your on-line documentation will be similar in organization to a textbook. The Table of Contents feature will help you organize your on-line documentation by Topics and Subtopics. A Topic is a like a chapter in the book. You may create any number of Topics and up to 31 Subtopics per Topic. Within this limitation of 31 Subtopics per Topic, you are free to choose the organization that you deem best for the project at hand. (See figure 3, Aplhabetic Index)

Fig. 3 Alphabetic Index

The Index is a most powerful organizing feature of HDS for it allows you to create a glossary and references to any message in your documentation. While the table of contents leads the user in a sequential manner, the Index allow fast random access. While the novice user is more likely to use the table of contents to navigate the documentation, the experienced user and the power user are more likely to use the index to find specific bits of information. The index must satisfy the novice and the power user.

The organization of the Index is hierarchical. The Index displays the list of Key Words in alphabetic (ASCII) order. You select a Key Word and then you are given a second multiple choice: Major Reference and General Reference. (See figure 4, Major Reference)

Major Reference

If there is a whole Topic or Subtopic dedicated to a Key Word, then the reference to that Topic or Subtopic is called a Major Reference. Visually, the method of access to a Major Reference is similar to the method of access to a Topic from the Table of Contents. This similarity creates an intuitive image of the importance of the reference.

You can create any number of references to any part of any message within your on-line documentation. These General References are shown in alphabetic (ASCII) order for each Key Word. Visually, the access to General References is different from the access to Major References in order to create an intuitive image of their relative importance and usage.

Fig. 4 Major Reference System

The Index feature allows you not only to create references to any part of the documentation, but it lets you write one or more messages for each Key Word. If you write a ‘Definition’ for each key word, then, the sum of these ‘Definitions’ constitutes your on-line glossary.

Cross References

The cross referencing feature is a powerful organizational aide for the author. Cross References are selected Key Words in Help messages that have been specifically outlined by the author to induce the reader to obtain additional information about the subject he is perusing. This feature permits you to include a certain amount of intelligence in the documentation, for example, in a passage about ‘Cut’, you might add the phrase: ‘See also, Paste’.

The outlined Key Word points to the Key Word’s list of references and messages. From this list the user selects the area of interest.

Visual Glossary

A visual glossary is a new type of book that only contains pictures with legends. A visual glossary is used to find the unknown names of familiar objects.

HDS has a Help Scrapbook where you may paste the icons, pictures or other graphic elements used by your application program. The user can browse through the Help Scrapbook to find information about things (doodads, icons, whatchamacallits, et al.) whose name he does not know, or has forgotten. It is often enough to add legends to the picture to describe it. If you need to give more information than would comfortably fit in a few legends, you may create a message associated with the picture.

List of Illustrations

The Help Scrapbook has an alphabetically ordered Catalog that acts like a list of illustrations in a book. If the user knows the name of the thing that he is looking for, he can find it faster by using this Catalog, instead of browsing through the Help Scrapbook.

Help for Menus

The most intuitive way to obtain help for a menu command is to follow the same procedure used to execute the menu commands, in other words: to execute a menu command, select it with the arrow pointer; to get help for a menu command, select it with the “?” pointer

To implement this feature, the Help and Help Editor desk accessories capture the application’s menu bar. When you select any of the application’s menu commands with the “?” pointer while the HDS accessories are active, you open a message for the command, instead of executing the command.

For the Menu Help feature to function properly with your program, it is absolutely essential that you follow Apple’s guidelines with respect to the programming and operation of your menus. Should there be any problems with the interaction between HDS and your menus, please contact Help Software’s technical staff. (See figure 5, below: Context Sensitive Help)

Context Sensitive Help

On-line context sensitive help is an implementation of Apple’s guidelines of giving the user extra help without referring him to external documentation. By the very nature of context sensitive help, it must be initiated from within the program. We suggest that you implement context sensitive help in two steps: (1) When the user hits ‘Command-?’, convert the pointer to a “?”. (2) When the user selects anything on the desk top with the “?” pointer: an icon, a menu item, or a field in a document, make your program call the Help desk accessory and passes it a parameter that indicates which message should be displayed. (See figure 7, Extended Alerts)

Extended Alerts

“Under no circumstances should an alert message refer the user to external documentation for further clarification. It should provide an adequate description of the information needed by the user to take appropriate action.” From The Macintosh User Interface Guidelines, Inside Macintosh, Page I-69.

Your application program can call the Help desk accessory to display a message that will not fit into an alert box. We suggest that you give the user the choice to either see the Extended Alert message or return to the application by adding a Help button to your alert boxes.

Help in Context and Extended Alerts are identical from a programming point of view, the only difference is the user’s perception of their functionality. You may create up to 65535 messages of this type and use them either as Help in Context messages or as Extended Alerts.

Good technical books have a section on how to use them. The About Help message can be edited. Thus, you can alter it to include such instructions as how you implemented the Help In Context, or your Extended Alert procedures. It also means that you can translate the About Help message into any language, in the event you export your program.

Book Mark

HDS provides the user with several bookmarks to keep track of his place in the documentation: (1) The Topic and Subtopic last read have check marks next to them. (2) The Help Scrapbook opens at the last place it was used. (3) The Key Word last selected in the Alphabetic Index is highlighted. (4) For the last Key Word used, the General Reference last selected is highlighted or the Subtopic read as a Main Reference has a check mark next to it.

Slide Show

Some messages are easier to understand if shown screen by screen; we call this feature Slide Show. Others messages are easier to read line by line (standard scroll). The Help Editor menu allows you to select the best type of scroll for each message.

The HDS uses a “?” pointer to indicate clearly that the Macintosh is currently in the Help mode of operation.

Help Font

This feature is aimed at the international market. There is no Help font as such. HDS uses the font installed in the on-line documentation file’s resource fork.

A pop up menu in the Open File box allows you to select the font you wish to install in the Help file that you are creating.

This means that a program interface written in English can be documented in any language and font. The reasons for storing a font in the resource fork of the HDS on-line documentation file are: (1) This font will not interfere with your application’s font menu. (2) If a user needs help, things should be as easy as possible. You do not have to worry whether the proper font is installed in the System file. Since each HDS on-line documentation file carries its own font, you can provide documentation for the same application in several languages.

Some software companies can afford to translate their programs into several languages, though most cannot. Therefore, in foreign lands, some programs operate in the native language, and others operate in English. This means that the foreign user must continually make a mental jump from ‘File’ to ‘Archivo’, and from ‘Open’ to ‘Abrir’. This is the opposite of consistency. Foreign technical words find their way into everyday language. In Latin America, terms such as Strike, Out, Foul and Fair are frequently used when talking baseball; these people don’t speak English, and yet everyone understands. In a similar manner, English technical terms are common in software packages written for the international market. It is often better to leave the user interface in English, and to give the explanations in the native language.

Many good reasons assist Apple Computer in promoting the ‘Localizing’ of Macintosh software. HDS offers an alternative solution that might be more adequate in some situations.

Invoking Help

There are three ways in which users can activate the Help desk accessory: (1) From the Apple Menu, (2) using ‘Command-?’ if you have implemented Help In Context and, (3) pressing the Help button in an alert box if you have implemented Extended Alerts.

An application program may be documented with HDS without implementing the Help In Context and Extended Alert features. This is the road that a user would take to document a program for which he does not have access to the source code. It is worth while for developers to implement these features in their programs, since the small overhead of extra code is more that offset by the advantages gained in user friendliness provided by these two features.

Access Path

Once the Help desk accessory has been invoked by any of the three methods shown above, the user has access to the on-line documentation in several ways. This information is never more than three operations away.

Sample Code to call Help from your program
/* Sample code for Help In Context */
/* and Extended Alert calls to the */
/* Help Desk Accessory using Aztec C */
/* Include the bold faced code in  */
/* your program  */

/* Desk manager library */
*include (desk.h)

/* Parameter block library*/
*include (pb.h)

/* Global variables to test for  */
/* the Help desk accessory*/
/* Help is the desk accessory refnum */
short Help=0;

/* inContext is the message to be  */
/* displayed*/
long inContext;

main()
{
doneflag= FALSE;

/* parameter block to call Help  */
ParamBlkRec param;

/* Main program loop */
while (!doneflag)
{
SystemTask();

/* If Help<0 then the Help desk  */
/* accessory is open */
/* If Help=WindowKind*/
/* of the active window then*/
/* the Help desk accessory is active */
If (Help<0 && Help==((WindowPeek)FrontWindow())
->windowKind)
 {
 /* Assign the parameter block*/
 /* values for a desk accessory  */
 /* control call */
 param.ioCompletion=NULL;

 /* accessory refnum assigned by */
 /* the OpenDesk Acc call */
 param.u.cp.csRefNum=Help;

 /* 5000 is the csCode for the*/
 /* InContext feature*/
 param.u.cp.csCode=5000;

 /* inContext is the message*/
 /* to be displayed*/
 *((long*)&(param.u.cp.
   csParam))=inContext;

 /* it’s an asynchronous call */
 PBControl(&param,TRUE);

 /* Reset Help */
 Help=0;
 }
 temp = GetNextEvent(everyEvent,
   &myEvent);
 switch(myEvent.what)
 {
 *
 *
 *

/* To call the Help desk accessory */
/* from a routine in your program, */
/* insert the following code*/
 *
 *
 *

/* Open the Help desk accessory  */
/* “\P” is a PASCAL String in Aztec C*/
/* “\O” is NULL  */

/* Help In Context or Extended Alert */
Help=OpenDeskAcc(“\P\OHelp”);

/* message to be displayed*/
inContext=num;
 *
 *
 *