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;
 *
 *
 *
 
AAPL
$99.18
Apple Inc.
-1.57
MSFT
$45.90
Microsoft Corpora
-0.46
GOOG
$568.27
Google Inc.
-9.09

MacTech Search:
Community Search:

Software Updates via MacUpdate

Cocktail Family License (5 Macs) 7.6.1 -...
Cocktail is a general purpose utility for OS X that lets you clean, repair and optimize your Mac. It is a powerful digital toolset that helps hundreds of thousands of Mac users around the world get... Read more
Cocktail 8.0 Beta 2 - General maintenanc...
Cocktail is a general purpose utility for OS X that lets you clean, repair and optimize your Mac. It is a powerful digital toolset that helps hundreds of thousands of Mac users around the world get... Read more
QuickBooks 2015 16.0.0.1352 R1 - Financi...
QuickBooks 2015 helps you manage your business easily and efficiently. Organize your finances all in one place, track money going in and out of your business, and spot areas where you can save.... Read more
Mac DVDRipper Pro 5.0.1 - Copy, backup,...
Mac DVDRipper Pro is the DVD backup solution that lets you protect your DVDs from scratches, save your batteries by reading your movies from your hard disk, manage your collection with just a few... Read more
Apple OS X bash Update 1.0 - Fix for sec...
The OS X bash Update fixes a security flaw in the bash UNIX shell on OS X 10.9.5 (also on OS X 10.8 and 10.7 [see Related Links below]). OS X 10.9.5 or later Downloads for OS X 10.8 and OS X 10.7 in... Read more
SyncTwoFolders 2.0.5 - Syncs two user-sp...
SyncTwoFolders simply synchronizes two folders. It supports synchronization across mounted network drives and it is a possibility to run a simulation showing in a log what will be done. Please visit... Read more
FinderPop 2.5.7 - Classic Mac utility, n...
FinderPop is a Universal preference pane that extends OS X's contextual menus using a FinderPop Items folder much as the Apple Menu Items folder used to do for the Apple menu. It has other features... Read more
VueScan 9.4.45 - Scanner software with a...
VueScan is a scanning program that works with most high-quality flatbed and film scanners to produce scans that have excellent color fidelity and color balance. VueScan is easy to use, and has... Read more
LibreOffice 4.3.2.2 - Free Open Source o...
LibreOffice is an office suite (word processor, spreadsheet, presentations, drawing tool) compatible with other major office suites. The Document Foundation is coordinating development and... Read more
calibre 2.4 - Complete e-library managem...
Calibre is a complete e-book library manager. Organize your collection, convert your books to multiple formats, and sync with all of your devices. Let Calibre be your multi-tasking digital... Read more

Latest Forum Discussions

See All

iKeywi - Customizable 5-Row Keyboard (U...
iKeywi - Customizable 5-Row Keyboard 1.0 Device: iOS Universal Category: Utilities Price: $.99, Version: 1.0 (iTunes) Description: Want to add an extra row to your iPhone/iPad? One of the most popular keyboard extension in iOS... | Read more »
Manage Your Cloud – Wunderlist Now Suppo...
Manage Your Cloud – Wunderlist Now Supports Dropbox Posted by Jessica Fisher on October 1st, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Nexticy Review
Nexticy Review By Jennifer Allen on October 1st, 2014 Our Rating: :: IDEAL FORM CREATIONiPad Only App - Designed for the iPad Nexticy allows you to make your own forms for research purposes or to organize your business better. It’s... | Read more »
Tiny Troopers: Alliance Marches onto the...
Tiny Troopers: Alliance Marches onto the App Store Tomorrow Posted by Jessica Fisher on October 1st, 2014 [ permalink ] Tiny Troopers: Alliance, by Kukouri, is a | Read more »
HeroCraft Introduces Unlimited Sequel to...
HeroCraft Introduces Unlimited Sequel to WW2: Sandbox. Strategy & Tactics Posted by Jessica Fisher on October 1st, 2014 [ permalink ] | Read more »
RGB Express Review
RGB Express Review By Jennifer Allen on October 1st, 2014 Our Rating: :: DELIGHTFUL PUZZLINGUniversal App - Designed for iPhone and iPad Guide trucks along their delivery routes in RGB Express, a testing but charming puzzle game... | Read more »
The Sagas of Fire*Wolf (Games)
The Sagas of Fire*Wolf 1.0 Device: iOS Universal Category: Games Price: $9.99, Version: 1.0 (iTunes) Description: | Read more »
BuggyFun Review
BuggyFun Review By Amy Solomon on October 1st, 2014 Our Rating: iPad Only App - Designed for the iPad BuggyFun allows children to create their own tracks for bugs to interact with for a unique open-ended experience.   | Read more »
Fold the Adventure Review
Fold the Adventure Review By Jennifer Allen on October 1st, 2014 Our Rating: :: AWKWARD FOLDSUniversal App - Designed for iPhone and iPad Fold pieces of paper to create platforms for a princely rabbit in this puzzle game; something... | Read more »
WW2: Sandbox. Strategy & Tactics (G...
WW2: Sandbox. Strategy & Tactics 1.0.0 Device: iOS Universal Category: Games Price: $9.99, Version: 1.0.0 (iTunes) Description: ***NOTE: Compatible with iPhone 4s and up, iPad 2 and up - may not work properly on earlier devices... | Read more »

Price Scanner via MacPrices.net

Amazon offers 13-inch MacBook Air for $899, $...
Amazon.com has the 13″ 1.4GHz 128GB MacBook Air on sale for $100 off MSRP including free shipping: - 13″ 1.4GHz 128GB MacBook Air: $899.99 Read more
Apple resting On Its iPhone Laurels? – The ‘B...
Apple calls its new iPhone 6 and 6 Plus “The Biggest Advancements in iPhone History,” but does reality live up to the hype? “Seldom have so many waited so breathlessly for so little,” tweeted veteran... Read more
Roundup of Apple Mac and iPad Education disco...
Purchase a new Mac or iPad at The Apple Store for Education and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free,... Read more
Apple Boycotts German Magazine Computer Bild...
Apple has revoked its PR accreditation of Germany’s Computer Bild, Europe’s best-selling PC magazine, in reaction to Bild’s posting of a “#Bentgate” YouTube video. Axel Telzerow, editor in chief of... Read more
iPhone 6 & iPhone 6 Plus Available in Chi...
Apple has announced that iPhone 6 and iPhone 6 Plus will be available in China beginning Friday, October 17 from the Apple Online Store (http://www.apple.com), Apple’s retail stores, and an expansive... Read more
MacBook Airs on sale for $100 off MSRP, start...
Best Buy has the new 2014 MacBook Airs on sale for $100 off MSRP on their online store. Choose free home shipping or free local store pickup (if available). Prices valid for online orders only, in-... Read more
Apple Releases OS X Mavericks bash Update 1.0...
Apple has released a patch update for OS X Mavericks users to address the recently-detected “Shellshock” security bug in BSD UNIX’s bash shell. Apple says only a few Mac users who had manually... Read more
Pivotal Payments Ready for Apple Pay – FlexPo...
Pivotal Payments, a provider of merchant services and global payment processing solutions, has announced its proprietary FlexPoint platform will support credit and debit transactions through Apple’s... Read more
iStabilizer Announces Tabarm — First Friction...
iStabilizer, a specialist in universal lightweight compact tripods, steady cams, dollies, mounts, and remotes for smartphones, tablets, and cameras, announced today the iStabilizer tabArm, the first... Read more
IStabilizer Flex Smartphone Tripod Wins Usa T...
iStabilizer, a specialist in universal lightweight compact tripods, steady cams, and other products for smartphones, tablets, and cameras, has announced today that its iStabilizer Flex smartphone... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Senior Event Manager, *Apple* Retail Market...
…This senior level position is responsible for leading and imagining the Apple Retail Team's global event strategy. Delivering an overarching brand story; in-store, Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
Project Manager / Business Analyst, WW *Appl...
…a senior project manager / business analyst to work within our Worldwide Apple Fulfillment Operations and the Business Process Re-engineering team. This role will work Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.