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
$101.32
Apple Inc.
+0.74
MSFT
$45.15
Microsoft Corpora
-0.07
GOOG
$582.56
Google Inc.
-0.81

MacTech Search:
Community Search:

Software Updates via MacUpdate

calibre 2.0.0 - Complete e-library manag...
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
Apple iMovie 10.0.5 - Edit personal vide...
With an all-new design, Apple iMovie lets you enjoy your videos like never before. Browse your clips more easily, instantly share your favorite moments, and create beautiful HD movies and Hollywood-... Read more
Apple Keynote 6.2.2 - Apple's prese...
Apple Keynote makes it simple to create and deliver beautiful presentations. Powerful tools and dazzling effects bring your ideas to life. You can work seamlessly between Mac and iOS devices. And... Read more
Apple Numbers 3.2.2 - Apple's sprea...
With Apple Numbers, sophisticated spreadsheets are just the start. The whole sheet is your canvas. Just add dramatic interactive charts, tables, and images that paint a revealing picture of your data... Read more
OpenOffice 4.1.1 - Free and open-source...
OpenOffice.org is both an Open Source product and a project. The product is a multi-platform office productivity suite. It includes the key desktop applications, such as a word processor,... Read more
Pages 5.2.2 - Apple's word processo...
Apple Pages is a powerful word processor that gives you everything you need to create documents that look beautiful. And read beautifully. It lets you work seamlessly between Mac and iOS devices. And... Read more
Quicken 2015 2.0.1 - Complete personal f...
The new Quicken 2015 helps you manage all your personal finances in one place, so you can see where you're spending and where you can save. Quicken automatically categorizes your financial... Read more
CleanMyMac 2.2.7 - Delete files that was...
CleanMyMac makes space for the things you love. Sporting a range of ingenious new features, CleanMyMac 2 lets you safely and intelligently scan and clean your entire system, delete large, unused... Read more
MacFamilyTree 7.2.4 - Create and explore...
MacFamilyTree gives genealogy a facelift: it's modern, interactive, incredibly fast, and easy to use. We're convinced that generations of chroniclers would have loved to trade in their genealogy... Read more
Videobox 4.1.1 - Download Flash video th...
Videobox allows you to quickly and easily download Flash video from most all of the popular video sites on the internet. Videobox will convert the video into a native Quicktime format so it's ready... Read more

Latest Forum Discussions

See All

Trolls vs Vikings Update Adds Over One H...
Trolls vs Vikings Update Adds Over One Hundred Levels, Reduces Item Cost, and More Posted by Ellis Spice on August 22nd, 2014 [ permalink ] | Read more »
SNK Celebrates the 20th Anniversary of T...
SNK Celebrates the 20th Anniversary of The King of Fighters With a Big Sale Posted by Ellis Spice on August 22nd, 2014 [ permalink ] | Read more »
It Came From Canada: Star Wars: Commande...
With a brand new Star Wars trilogy on the horizon, prepare yourselves for Disney and George Lucas’s space fantasy throwback to be more omnipresent than ever before. So it should come as no surprise that new adventures in that galaxy far, far away... | Read more »
Swing Copters Review
Swing Copters Review By Jordan Minor on August 22nd, 2014 Our Rating: :: DIE TRYINGUniversal App - Designed for iPhone and iPad The creator of Flappy Bird is back with a vengeance.   | Read more »
The Outcast Review
The Outcast Review By Nadia Oxford on August 22nd, 2014 Our Rating: :: HANDS OFF. WAY OFF.Universal App - Designed for iPhone and iPad It’s easy to see what The Outcast is trying for, but its execution needs a lot of work.   | Read more »
Brain+ Review
Brain+ Review By Nadia Oxford on August 22nd, 2014 Our Rating: :: DIM BULBUniversal App - Designed for iPhone and iPad Brain+ is just another entry in an over-saturated brain-training marketplace – and not a particularly fun entry... | Read more »
The Witcher Battle Arena – New Gameplay...
The Witcher Battle Arena – New Gameplay Trailer Revealed Posted by Jessica Fisher on August 22nd, 2014 [ permalink ] Based in the Witcher universe, | Read more »
Max Gentlemen Review
Max Gentlemen Review By Jennifer Allen on August 22nd, 2014 Our Rating: :: OUTSTAYING ITS WELCOMEiPhone App - Designed for the iPhone, compatible with the iPad Max Gentlemen seems pretty quirky initially but that appeal wears thin... | Read more »
Club Penguin Gets Frozen All Over in Lat...
Club Penguin Gets Frozen All Over in Latest Takeover Event Posted by Ellis Spice on August 22nd, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Doctor Who: Legacy Review
Doctor Who: Legacy Review By Jennifer Allen on August 22nd, 2014 Our Rating: :: RUN OF THE MILLUniversal App - Designed for iPhone and iPad Doctor Who: Legacy is an ok match-3 puzzle game, but it lacks some much needed personality... | Read more »

Price Scanner via MacPrices.net

Leftover 15-inch 2.0GHz Retina MacBook Pros a...
B&H Photo has leftover previous-generation 15″ 2.0GHz Retina MacBook Pros now available for $1599 including free shipping plus NY sales tax only. Their price is $400 off original MSRP. B&H... Read more
Pro.Calendar – New Productivity App for iPad...
Austin, Texas based mobile business and productivity app developer LightArrow, Inc. has announced Pro.Calendar, a powerful and intuitive calendar app with eight versatile calendar options including... Read more
SanDisk Ultra II SSD — Supercharge Your Syste...
SanDisk Corporation has announced the new SanDisk Ultra II SSD with enhanced SSD Dashboard. The new drive is designed to deliver a cost-effective and easy upgrade solution for PC owners looking to... Read more
Samsung and Barnes & Noble Introduce New...
Samsung Electronics America and NOOK Media, a subsidiary of Barnes & Noble, Inc. have announced the introduction of the new Samsung Galaxy Tab 4 NOOK, a 7-inch tablet combining Samsung’s leading... Read more
21-inch iMacs on sale for up to $150 off MSRP
B&H Photo has 21″ iMacs on sale for up to $150 off MSRP including free shipping plus NY sales tax only. B&H will also include a free copy of Parallels Desktop software: - 21″ 2.7GHz iMac: $... Read more
27-inch 3.2GHz iMac on sale for $1698, save $...
Abt has the 27″ 3.2GHz iMac on sale for $1698 including free shipping. Their price is $101 off MSRP. Read more
Mac Backup Guru 2.0 Drive Backup/Cloneing Uti...
Mac Backup Guru developer MacDaddy has released Mac Backup Guru 2.0, offering new and enhanced advanced features, such as bootable backups, synchronised volumes and folders, and a Snapshot mode that... Read more
Operate GE’s New Free-Standing KItchen Range...
Think you accidentally left the oven on? Switch it off while on the go. The new free-standing Profile™ Series gas and electric ranges are GE’s second cooking appliances, following their wall oven, to... Read more
Parallels Announces Parallels Desktop 10 for...
The no. 1-selling software for running Windows applications on a Mac becomes an even easier choice for millions of consumers and IT professionals worldwide with the launch of the most powerful... Read more
Apple now offering certified refurbished 2014...
 The Apple Store is now offering Apple Certified Refurbished 2014 MacBook Airs for up to $180 off the cost of new models. An Apple one-year warranty is included with each MacBook, and shipping is... 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
Position Opening at *Apple* - Apple (United...
**Job Summary** As more and more people discover Apple , they visit our stores seeking ways to incorporate our products into their lives. It's your job, as a Store Read more
Position Opening at *Apple* - Apple (United...
…Summary** As a Specialist, you help create the energy and excitement around Apple products, providing the right solutions and getting products into customers' hands. You Read more
Project Manager, *Apple* Financial Services...
**Job Summary** Apple Financial Services (AFS) offers consumers, businesses and educational institutions ways to finance Apple purchases. We work with national and Read more
*Apple* Solutions Consultant (ASC)- Retail S...
**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
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.