Tip of the month from
PRC
November
1998
On-screen help/manuals/tutorials
PRC AcosHelp information included: 26 Sep. '03
Microsoft HTML help Workshop
info added: 17 Jan. '99
One more HTML-help example added, (click
): 4 Nov. '98
Published: 2 November 1998
We accept Mastercard/Eurocard/Maestro/JBC and Visa!
Tip of the month is edited by Peter
Ring, PRC (Peter Ring Consultants, Denmark)
- consultants on how to write
user friendly manuals
If you have
corrections, better texts or suggestions for improvements, please let me
know.
Contents
Introduction
On-screen help has mainly been
used for software products, but it is increasingly becoming used for complex
professional products, too, e.g. control equipment including a system PC.
Currently there are seven different
types of on-screen help/manuals/tutorials:
- The classical help function
- Wizards
- "Helpers"
- On-screen book type help
(e.g. Acrobat)
- On-screen videos
- HTML-help
- Interactive tutorials
None of them seems to be "the
final solution".
Which one or which combination
to select depends consequently of a large number of factors, e.g.
- Which kind of product are
we to document?
- Which users are to be addressed?
- Economy!
Let's look at their advantages
and disadvantages - in general and one-by-one?
General advantages and disadvantages of on-screen manuals, etc.
Advantages
- Can contain internal and
external links (all modern versions).
- Can contain large amounts
of information without having a "bulky look".
- Relatively cheap or completely
cost-free distribution.
- Fast and easy to update
from the Internet.
Disadvantages
- Difficult to display large
screen-shots without reducing the image quality. The problem is, that the
original on-screen fonts and thin lines are optimised for the full screen
and can't be reduced without becoming almost unreadable. For a partial solution,
see "tip of the month" for June 1998
: "Resizing of bitmaps".
- In most cases, available
for "pirate-users, too.
- The user must have access
to a computer with a suitable reader programme.
Information to be included OUTSIDE the on-screen manual/tutorial
Some information need to be
presented to the user outside the on-screen
manual:
- Order of magnitude 15% of
all users want to read the manual from A to Z at least once
before they even try starting the installation
. They need at least a "How to get started" chapter/booklet in order to
reassure themselves, that they are not going to do anything wrong during
installation! On-screen guidance during the installation is not enough!
- How to start
the installation programme
. If it is advisable to terminate all other programmes before starting
the installation - incl. any virus checker - before starting the installation,
tell it here, too!
- What to do
if you for some odd reason can NOT access the on-screen help
. This information should include the local hot-line telephone number.
The classical "help" function
The classical "Help" function
has developed over the last at least 20 years from primitive text files to
today's much more sophisticated functions including links, images, context
oriented entries, sounds, videos, etc.
Advantages
- Possibilities for explaining
professional terms, abbreviations, etc. to beginners without disturbing any
professional's reading habits.
- Not page oriented: a "page"
can have any size from one line to thousands of lines with as many graphics
as you want.
- See also
"General"
.
Disadvantages
- Difficult/impossible to use
the same content for a paper-based manual and the on-screen help.
- Many people have problems
getting it on top of the screen windows at the same time as they are performing
the processes described. They consequently almost automatically print the
pages needed.
- See also
"General"
.
Wizards
Wizards are not really on-screen
help, it is rather a semi-automatic procedure, where the user has to take
some decisions in some of the steps. Make sure, the user knows the background
for answering the questions. Very often, they don't! If not, offer some help.
Wizards are most often used in addition to some other sort of help, e.g.
"classical" help.
Advantages
- Very useful method to guide
the user through a complex procedure.
- Very suited for (in principle)
one-time procedures like installation.
- See also
"General"
.
Disadvantages
- The user never learns the
"real" procedure - if such one exists at all.
- See also
"General"
.
"Helpers"
Helpers are the "intelligent"
help functions used e.g. in MS Word 97, where you e.g. can type in a question
and get assistance. Helpers are most often used in addition to some other
sort of help, e.g. "classical" help.
Advantages
Disadvantages
- Still not intelligent enough!
Example: if the user don't find the "correct" term no meaningful help will
appear. Try e.g. in MS Word 97 to ask for info about "secret" text instead
of "hidden" text!
- If unsuccessful a couple
of times, many users give it up!
- Many users - especially
academics - find it "childish" and consequently avoid using it.
- See also
"General"
.
The on-screen book type of help
The Adobe Acrobat format seems
to have won the race becoming the de facto standard.
Advantages
- You can use the files for
the printed version directly, and even include internal and external links.
- List of contents and index
can automatically become links.
- Easy to printout with a
100% controlled layout.
- Platform independent (Windows,
Mac, UNIX).
- See also
"General"
.
Disadvantages
- Page oriented.
- Dependent of the font used:
may be difficult to read on a low-resolution (800x600 or less) screen.
- Many people still don't
have any Acrobat reader, or still only have the Acrobat 2.0 reader. Solution:
always include the installation programme for the reader with the help/manual
file.
- See also
"General"
.
In September 2003 PRC launched PRC AcosHelp
which makes it possible to make context sensitive help with Adobe Acrobat files (PDF-files).
For further information click the banner below:
On-screen videos
On-screen videos have mainly been
used for start-up tutorials. Video type screendumps can e.g. be made with
SnagIt
(shareware).
Advantages
- Good for weak readers.
- Good for taking away the
"mysteries" about e.g. a new kind of a programme.
- See also
"General"
.
Disadvantages
- Takes up many megabytes of
space (use e.g. CD-ROM).
- Lack of standardisation
of Video formats and players. Include a suitable player with the CD-ROM.
- Fairly expensive to make.
- See also
"General"
.
HTML-help
The typical design is today a
3-field "frames" design:
- Heading (most often company
name and product i.d.).
- Table Of Contents with links.
- The desired function related
information.
HTML help has been announced to
be the future, but there are still (October 1998) only very few examples
available, e.g. http://www.bofa.com
(Bank of America), http://www.delta-air.com
(Delta Airlines) and the new Mac OS 8.5 (no Internet address).
There are two main suppliers
of professional software:
- JavaHelp - Sun Microsystems
HTML.
- Help - Microsoft.
- (To my knowledge, Netscape
has given up their NetHelp.)
There is still no real standard for HTML based help systems. Microsoft's
HTMLhelp and the free(!) MS HTML Help Workshop 1.2 downloadable (4 MB) from
Microsoft's website (
http://www.microsoft.com/workshop/author/htmlhelp/download.asp
) is a good guess for a possible future standard, although not very ideal,
yet. MS HTML help system is based on a special reader, hh.exe (27 kB), which
displays the help function in two windows, one for navigation and one for
the info. All help html-files, image files, the index file, etc. is compiled
into one .chm helpfile.
For more info, see e.g.
http://msdn.microsoft.com/developer/news/htmlhelp.htm
(registration may be requested).
Advantages
- Well-known GUI (Graphical
User Interface).
- Platform independent (Windows,
Mac, UNIX).
- Well suited for team development
because of many independent basic files.
- Production tools widely
known and available - except if you want to distribute as one file.
- See also
"General"
.
Disadvantages
- All the well-known Internet
problems, especially answering time and network stability.
- Lack of 100% layout control
(like web pages).
- At least 800x600, preferably
1024x768+ screen resolution needed. And most people are still using 800x600
or even 640x480 screens!
- Difficult to find out what
is going to be printed out by a print command.
- Problems with free text
search.
- Browser needed.
- Browsers are different !!!
- Immature product under development
- few practical experiences.
- See also
"General"
.
Thank you to Rolf Molich, DialogDesign,
Denmark (molich@acm.org
) for compiling this information.
Interactive tutorials
An interactive tutorial is a dummy
version of the real product, where the user can be guided through the procedures
step-by-step by a screen text, by a voice, or both.
There are a number of software
packages available, e.g. Macromedia Authorware and Designer, Corel Click
& Create, and Asymetrix Toolbook Multimedia, C++, Borland Delphi and
MS Visual Basic. Personally, I have good experiences with MS Visual Basic
5.
Advantages
- Can be made very instructive.
- You can learn to work with
a costly equipment without any risk of damaging anything or disturbing the
operation of product (e.g. an electricity plant or a ship)
- Useful in a sales situation
to explain how easy your product is to learn and use.
- See also
"General"
.
Disadvantages
- Fairly costly to make per
procedure, especially setting up the dummy for the first procedures.
- Takes up many megabytes
of space (use e.g. CD-ROM).
- See also
"General"
.
If you disagree
with these ideas - or have other relevant points, experiences, or ideas +/-,
please e-mail me
!
Ideas
for new "Tip of the month" subjects are VERY welcome, too!
Go to
last month's tip
.
Go to a list of old tips
.
Return to the User Friendly Manuals' homepage
.
Free update service
Click here
if you want to receive an e-mail whenever this website is updated with
major new information, e.g. with a new "tip of the month" or a new interesting
link. The e-mail will briefly describe the content of the update.
.
.
.
.
.
.
.