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