TweetFollow Us on Twitter

Help System
Volume Number:3
Issue Number:11
Column Tag:The Visiting Developer

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;
 *
 *
 *
 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Latest Forum Discussions

See All

Whitethorn Games combines two completely...
If you have ever gone fishing then you know that it is a lesson in patience, sitting around waiting for a bite that may never come. Well, that's because you have been doing it wrong, since as Whitehorn Games now demonstrates in new release Skate... | Read more »
Call of Duty Warzone is a Waiting Simula...
It's always fun when a splashy multiplayer game comes to mobile because they are few and far between, so I was excited to see the notification about Call of Duty: Warzone Mobile (finally) launching last week and wanted to try it out. As someone who... | Read more »
Albion Online introduces some massive ne...
Sandbox Interactive has announced an upcoming update to its flagship MMORPG Albion Online, containing massive updates to its existing guild Vs guild systems. Someone clearly rewatched the Helms Deep battle in Lord of the Rings and spent the next... | Read more »
Chucklefish announces launch date of the...
Chucklefish, the indie London-based team we probably all know from developing Terraria or their stint publishing Stardew Valley, has revealed the mobile release date for roguelike deck-builder Wildfrost. Developed by Gaziter and Deadpan Games, the... | Read more »
Netmarble opens pre-registration for act...
It has been close to three years since Netmarble announced they would be adapting the smash series Solo Leveling into a video game, and at last, they have announced the opening of pre-orders for Solo Leveling: Arise. [Read more] | Read more »
PUBG Mobile celebrates sixth anniversary...
For the past six years, PUBG Mobile has been one of the most popular shooters you can play in the palm of your hand, and Krafton is celebrating this milestone and many years of ups by teaming up with hit music man JVKE to create a special song for... | Read more »
ASTRA: Knights of Veda refuse to pump th...
In perhaps the most recent example of being incredibly eager, ASTRA: Knights of Veda has dropped its second collaboration with South Korean boyband Seventeen, named so as it consists of exactly thirteen members and a video collaboration with Lee... | Read more »
Collect all your cats and caterpillars a...
If you are growing tired of trying to build a town with your phone by using it as a tiny, ineffectual shover then fear no longer, as Independent Arts Software has announced the upcoming release of Construction Simulator 4, from the critically... | Read more »
Backbone complete its lineup of 2nd Gene...
With all the ports of big AAA games that have been coming to mobile, it is becoming more convenient than ever to own a good controller, and to help with this Backbone has announced the completion of their 2nd generation product lineup with their... | Read more »
Zenless Zone Zero opens entries for its...
miHoYo, aka HoYoverse, has become such a big name in mobile gaming that it's hard to believe that arguably their flagship title, Genshin Impact, is only three and a half years old. Now, they continue the road to the next title in their world, with... | Read more »

Price Scanner via MacPrices.net

B&H has Apple’s 13-inch M2 MacBook Airs o...
B&H Photo has 13″ MacBook Airs with M2 CPUs and 256GB of storage in stock and on sale for up to $150 off Apple’s new MSRP, starting at only $849. Free 1-2 day delivery is available to most US... Read more
M2 Mac minis on sale for $100-$200 off MSRP,...
B&H Photo has Apple’s M2-powered Mac minis back in stock and on sale today for $100-$200 off MSRP. Free 1-2 day shipping is available for most US addresses: – Mac mini M2/256GB SSD: $499, save $... Read more
Mac Studios with M2 Max and M2 Ultra CPUs on...
B&H Photo has standard-configuration Mac Studios with Apple’s M2 Max & Ultra CPUs in stock today and on Easter sale for $200 off MSRP. Their prices are the lowest available for these models... Read more
Deal Alert! B&H Photo has Apple’s 14-inch...
B&H Photo has new Gray and Black 14″ M3, M3 Pro, and M3 Max MacBook Pros on sale for $200-$300 off MSRP, starting at only $1399. B&H offers free 1-2 day delivery to most US addresses: – 14″ 8... Read more
Department Of Justice Sets Sights On Apple In...
NEWS – The ball has finally dropped on the big Apple. The ball (metaphorically speaking) — an antitrust lawsuit filed in the U.S. on March 21 by the Department of Justice (DOJ) — came down following... Read more
New 13-inch M3 MacBook Air on sale for $999,...
Amazon has Apple’s new 13″ M3 MacBook Air on sale for $100 off MSRP for the first time, now just $999 shipped. Shipping is free: – 13″ MacBook Air (8GB RAM/256GB SSD/Space Gray): $999 $100 off MSRP... Read more
Amazon has Apple’s 9th-generation WiFi iPads...
Amazon has Apple’s 9th generation 10.2″ WiFi iPads on sale for $80-$100 off MSRP, starting only $249. Their prices are the lowest available for new iPads anywhere: – 10″ 64GB WiFi iPad (Space Gray or... Read more
Discounted 14-inch M3 MacBook Pros with 16GB...
Apple retailer Expercom has 14″ MacBook Pros with M3 CPUs and 16GB of standard memory discounted by up to $120 off Apple’s MSRP: – 14″ M3 MacBook Pro (16GB RAM/256GB SSD): $1691.06 $108 off MSRP – 14... Read more
Clearance 15-inch M2 MacBook Airs on sale for...
B&H Photo has Apple’s 15″ MacBook Airs with M2 CPUs (8GB RAM/256GB SSD) in stock today and on clearance sale for $999 in all four colors. Free 1-2 delivery is available to most US addresses.... Read more
Clearance 13-inch M1 MacBook Airs drop to onl...
B&H has Apple’s base 13″ M1 MacBook Air (Space Gray, Silver, & Gold) in stock and on clearance sale today for $300 off MSRP, only $699. Free 1-2 day shipping is available to most addresses in... Read more

Jobs Board

Medical Assistant - Surgical Oncology- *Apple...
Medical Assistant - Surgical Oncology- Apple Hill Location: WellSpan Medical Group, York, PA Schedule: Full Time Sign-On Bonus Eligible Remote/Hybrid Regular Apply Read more
Omnichannel Associate - *Apple* Blossom Mal...
Omnichannel Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Cashier - *Apple* Blossom Mall - JCPenney (...
Cashier - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Blossom Mall Read more
Operations Associate - *Apple* Blossom Mall...
Operations Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Business Analyst | *Apple* Pay - Banco Popu...
Business Analyst | Apple PayApply now " Apply now + Apply Now + Start applying with LinkedIn Start + Please wait Date:Mar 19, 2024 Location: San Juan-Cupey, PR Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.