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
$567.67
Apple Inc.
+42.92
MSFT
$39.63
Microsoft Corpora
-0.06
GOOG
$524.46
Google Inc.
-2.48

MacTech Search:
Community Search:

Software Updates via MacUpdate

Ember 1.5.1 - Versatile digital scrapboo...
Ember (formerly LittleSnapper) is your digital scrapbook of things that inspire you: websites, photos, apps or other things. Just drag in images that you want to keep, organize them into relevant... Read more
Cyberduck 4.4.4 - FTP and SFTP browser....
Cyberduck is a robust FTP/FTP-TLS/SFTP browser for the Mac whose lack of visual clutter and cleverly intuitive features make it easy to use. Support for external editors and system technologies such... Read more
TechTool Pro 7.0.3 - Hard drive and syst...
TechTool Pro is now 7, and this is the most advanced version of the acclaimed Macintosh troubleshooting utility created in its 20-year history. Micromat has redeveloped TechTool Pro 7 to be fully 64... Read more
MacFamilyTree 7.1.6 - 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
EtreCheck 1.9.9 - For troubleshooting yo...
EtreCheck is a simple little app to display the important details of your system configuration and allow you to copy that information to the Clipboard. It is meant to be used with Apple Support... Read more
TeamViewer 9.0.28116 - Establish remote...
TeamViewer gives you remote control of any computer or Mac over the Internet within seconds, or can be used for online meetings. Find out why more than 200 million users trust TeamViewer! Free for... Read more
Viber 4.1.0 - Send messages and make cal...
Viber lets you send free messages and make free calls to other Viber users, on any device and network, in any country! Viber syncs your contacts, messages and call history with your mobile device,... Read more
Apple iOS 7.1.1 - The latest version of...
The latest version of iOS can be downloaded through iTunes. Apple iOS 7 brings an all-new design and all-new features. Simplicity Simplicity is often equated with minimalism. Yet true simplicity is... Read more
1Password 4.3 - Powerful password manage...
1Password is a password manager that uniquely brings you both security and convenience. It is the only program that provides anti-phishing protection and goes beyond password management by adding Web... Read more
Lens Blur 1.3.0 - True out-of-focus boke...
Let Lens Blur transform your existing photo into true SLR-quality out-of-focus bokeh effect! Everyone needs a gorgeous personalized background for a social profile, blog, Web/UI design, presentation... Read more

Latest Forum Discussions

See All

Soccer Rally 2 Review
Soccer Rally 2 Review By Carter Dotson on April 24th, 2014 Our Rating: :: GOALKEEPINGUniversal App - Designed for iPhone and iPad Soccer Rally 2 is the most serious vehicular soccer game ever created.   | Read more »
Galaxy Conquerors Review
Galaxy Conquerors Review By Jennifer Allen on April 24th, 2014 Our Rating: :: RETRO SHOOTINGUniversal App - Designed for iPhone and iPad Old school shooting is fun but inaccurate in Galaxy Conquerors.   | Read more »
Yomi Review
Yomi Review By Rob Thomas on April 24th, 2014 Our Rating: :: C-C-C-COMBO BREAKERiPad Only App - Designed for the iPad Round One – Fight! No quarters required for this iOS adaptation of a tabletop adaptation of the arcade fighting... | Read more »
Injustice: Gods Among Us Updated with Ne...
Injustice: Gods Among Us Updated with New Characters, Leaderboards, Gear, and Online Multiplayer Posted by Rob Rich on April 24th, 2014 [ | Read more »
Spin It Review
Spin It Review By Jordan Minor on April 24th, 2014 Our Rating: :: SPIN ME RIGHT ROUNDUniversal App - Designed for iPhone and iPad Spin It has a fine puzzle game model, but its execution lacks energy.   | Read more »
Productivity App NoteSuite is Having its...
Productivity App NoteSuite is Having its Biggest Sale Ever, Just for One Week Posted by Rob Rich on April 24th, 2014 [ permalink ] | Read more »
Wayward Souls Review
Wayward Souls Review By Carter Dotson on April 24th, 2014 Our Rating: :: CARRY ON, WAYWARD SONUniversal App - Designed for iPhone and iPad Wayward Souls is a roguelike-inspired action-RPG that sets a high bar for other games to... | Read more »
The Sandbox Gets Update, Receives New Ca...
The Sandbox Gets Update, Receives New Campaign and New Elements Posted by Tre Lawrence on April 24th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Football Management Simulator One For El...
Football Management Simulator One For Eleven Released Worldwide Today for iOS Posted by Simon Reed on April 24th, 2014 [ permalink ] Free-To-Play football management title One For E | Read more »
Leo’s Fortune Review
Leo’s Fortune Review By Jordan Minor on April 24th, 2014 Our Rating: :: FORTUNATE SONUniversal App - Designed for iPhone and iPad Leo’s Fortune delivers a platforming experience as creative and refined as any console game.   | Read more »

Price Scanner via MacPrices.net

Strong iPhone Sales Drive Apple Record March...
Apple on Wednesday announced financial results for its fiscal 2014 second quarter ended March 29, 2014. The Company posted quarterly revenue of $45.6 billion and quarterly net profit of $10.2 billion... Read more
Award-Winning NoteSuite Productivity App is $...
Minneapolis based Theory.io has announced an 80-Percent Markdown NoteSuite for iPad. NoteSuite helps users stay organized by capturing their notes, to-dos and documents in one organized place.... Read more
16GB 1st generation iPad mini available for $...
Radio Shack has a select number of refurbished 1st generation 16GB WiFi iPad minis available for $199.99 on their online store. Choose free shipping or free ship-to-store. We expect these to sell out... Read more
13-inch 2.5GHz MacBook Pro on sale for $100 o...
B&H Photo has the 13″ 2.5GHz MacBook Pro on sale for $1099 including free shipping plus NY sales tax only. Their price is $100 off MSRP. Read more
iPad Sales “Lull” A Reality Correction Of Unm...
I have lots of time for Jean-Louis Gassée, the former Apple Computer executive (1981 to 1990) who succeeded Steve Jobs as head of Macintosh development when the latter was dismissed in 1985. Mr.... Read more
Apple Makes OS X Betas Available To All – Wit...
Apple’s OS X Beta Seed Program, which lets you install the latest pre-release builds, try it out, and submit your feedback, is now open to anyone who wants to sign on rather than to developers and... Read more
Apple Releases iOS 7.1.1 Update
The latest iOS 7.1.1 update contains improvements, bug fixes and security updates, including: • Further improvements to Touch ID fingerprint recognition • Fixes a bug that could impact keyboard... Read more
Logitech Announces Thinner, Lighter, More Fle...
Logitech has announced an update to its Ultrathin for iPad Air, iPad mini and iPad mini with Retina display, improving the flexibility and design of its award-winning predecessor with an even thinner... Read more
Logitech Introduces Hinge, Big Bang and Turna...
Logitech has announced expansion of its tablet product line with three new cases – the Logitech Hinge, the Logitech Big Bang and the Logitech Turnaround – each for the iPad Air, iPad mini and iPad... Read more
WaterField’s Rough Rider Leather Messenger Ba...
WaterField Designs have announced the new 15-inch size of their popular Rough Rider leather messenger bag, a vintage-looking bag that combines Old West charm and ruggedness with distinctly modern... Read more

Jobs Board

*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
*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
Position Opening at *Apple* - Apple (United...
…customers purchase our products, you're the one who helps them get more out of their new Apple technology. Your day in the Apple Store is filled with a range of 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
*Apple* Inc. Research Data Specialist - Appl...
…of Worldwide Market Research & Intelligence. The team is responsible for conducting Apple branded consumer market research. It is also responsible for analyzing data Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.