.

,
Design Guidelines
Contents

About This

Design 1
1 I ntroduction
1 Software
1 N ew R ESET Features
1 N ew Apple 80 - Column Text Cards
2 Hand Controls and the APPLE Keys
2 New Apple l i e Firmware
3 Peripheral Card Firmware
4 BASIC Protocol
4 Pascal 1.0 Protocol
4 Pascal 1 .1 Protocol
7 Hardware

9
9 I ntroduction
10 Good H u man I nterfaces: So Often Elusive
10 A Planning and Testing M ethodology
10 Planning : the User Profile
14 Testing
19 Goals
19 Simplicity
19 Consistency
20 Efficiency
20 Self-teaching
20 Speediness
21 Minimum Strain on the User's M e mory
21 Honesty
21 G eneral Pr ogram Str u ctur e
22 Keep It Simple
22 Make It Fam iliar And Intuitive
24 I nput
25 The (Apple I I BASIC) Blinking- b ox Cursor
25 The ( Pascal) Solid-box Cur sor
26 The New I nser t/Delete Cursor
30 Cursor Movement with No Action Taken
30 Keyword Matching Dur i n g I n put: the Disam b i g uator
34 " Pr ess R ETU RN to continue"
35 Displays with Several I n put Statements
35 Err ors
37 Defaults
38 Displays
38 I nverse, Flash , Focus
38 Vocab ulary
39 Title Pages
39 Help
40 Menus
42 Keywor d Displays
43 Keep Them I nfor m ed When You Ar e Away

iii
About This Guide

This guide is divided into two parts . Part I contains reco m m e ndations to
software, firmware and hardware designers who want their products to
work smoothly with the Apple l i e, as well as the Apple I I and I I Plus.
These recommendations pertain to the i nterface between Apple II
Series computers and the products that are to work with the m .

Part I I pertains to the interface between software products a n d their

h uman users . The recommendations i n this section of the guide apply to
designers of software for Apple 1//s as well as Apple l i s . The user
interface g u idelines derive from the experience of countless Apple I I and
Ill users, as observed by more than a doz e n computer and teac h i n g
professionals . These guidelines s h o u l d make it easier f o r both
programmers and users to create and benefit from the tools that Apple
computers put at their disposal .

v
Part I
Product Design Guidelines
Introduction
This section contains guidelines for designers of software , peripheral
card firmware , and hardware i ntended for use with the Apple l i e . Also
refer to the sections of the Apple lie Reference Manual (Apple Product
N u m b e r A2 L2005 ) pert inent to t he product you are desi g n i n g .

Software
Most of the software guidelines pertain to four new features of the
Apple l i e :

1. The new R E s E T features and their i m p l ications .

2. The Apple l i e 80- column text cards and the need to check for the
presence of such a card and turn it on and off at appropriate times .

3. The o P E N - A P P L E and s o L 1 o - A P P L E keys and the fact that they

are electrically connected to the push b u ttons of hand controls # 0
and # 1 , respectively .

4. The n ew firmware , including enhanced M o n it o r program function s ,

expanded keyb oard ROM m a p with lowercase c haracters , and
twofold video display ROM map for primary and alternate character
set display .

The Apple l i e has all 6 4 K of it s m emory in RAM . A reset now affects the
cont ents of what used t o b e the " language card" area of main memory.

1. Do not require the use of the R E s E T key d u r i n g prog ram o p e ratio n

u n l ess y o u a r e n o t concerned that the b an k-switc h e d R A M (former
language card addresses) will b e switc h e d out.

2. Have BASIC or assembly lang uage programs start u p using the

o P E N - A P P L E c o N T R o L - R E s E T sequence rath e r than P R# s (slot s
for the startu p disk drive) . This reco m m e n dation is related to the
req u i rements of the new Apple 80 -col u m n text card s .

New Apple 80-Cn/urrsn TJ:Jxf Cards

These guidelines apply to BASIC and assem b ly lan g uage programs and
their calls to Monitor service routines.

1. Have any greeting prog ram 's first action b e to determ i n e if an

80 -column text card is in the system (see Peripheral Card Firmware
section b elow for identification methods) .

1
 2. Make sure that an 80 -col u m n card i s i nstalled before attem pting to
turn it on ; otherwise , unpredicta ble system conditions may result.

3. To turn on the Apple l i e 80 -column firmware , use P R #3 o r the

equivalent. The Apple 80 -col u m n firmware is associated with slot
3 for com pati bility with the Apple Pascal Operati n g Syste m .

4. Do not use P R #O to turn off the 80 -col u m n firmware . To turn it off ,

issue a C O N T R O L - U ( N A K character ; decimal code 2 1 ) .

5. Never have a program issue a P R #O o r I N #O w h i l e the 80 -colu m n

fi rmware is active .

6. Before sending output to devices other than the video display , issue
a c o N T R o L - L ( Form Feed ch aracter , deci mal code 1 2) to clear
the scree n , then a c o N T R o L - u to turn off the 80 -colu m n firmware .

7. If the 80 -column firmware is active , look at location 49 1 52 ($ COOO )

d irectly to check for a keypress . If you use the BASIC G ET
command or the Monitor KEV I N routi n e , each E s c keypress w i l l be
executed before its mod ifyi n g escape code can be retrieve d .

8. I f the 80 -column firmware is active, a program should not attempt to

display flashing lowercase characters ; they are not available in the
alternate character set.

9. I f your software turns o n the 80 -col u m n firmware , b e sure i t turns it

off before ending.

The Pascal Operating System automatically checks for the presence of

an 80 -column text card in slot 3 or the AUX CON N ECTOR slot. and turns
on the 80 -column firmware if such a card is present.

'"land Contro/t; and the APPLE Keys

The new o P E N - A P P L E key is conn ected to the pushbu tton of hand
control #0 , and the new s o L I D - A P P L E key is connected to the
pushbutton of hand control #1. Therefore , do not have a p rog ram
check for the absence of hand controls by checking whether both
push buttons have been pressed . I n stead , have the prog ram wait for a
count of 5 1 2 (twice the normal count) and see if the hand control t i m e r
has t i m e d out. If not, no h a n d controls a r e connected .

Nevu Ap,le fie Firmware

The Apple l i e Mon itor has been carefully rewritten to maintain all the
same entry points as those published in the original Apple II Reference
Manual . (The same entry points are , of course , also listed i n the
Apple l i e Reference Manual . ) At the same tim e , the Mon itor screen-

2
handling routines have been changed to accomodate the requirements
of 80 -column display.

The keyboard ROM map now features lowercase characters as well as

several characters not directly available on the Apple I I and I I Plus
keyboard .

To adapt software to these new features , follow these guidelines:

1. Either avoid performing checksums o n the resident firmware or be

prepared to accept the checksum outcom e of each model of
Apple I I that the software will run on .

2. Make sure that the program i s designed to recognize lowercase

characters or to convert them to upper case as necessary .

3. Make sure the program reacts appropriately to the alternate single

quote character (decimal code 9 6 ) now on the keyboard , as well as
the more commonly used single quote character ( d ecimal code 39 )
that has always been present on Apple I I keyboard s .

4. Programs that compensated for the absence of certain characters

(for example, " or I ) do not need to do so for the Apple l i e .

5. If a program uses Mon itor input/output routin e s , it should not use the
80 -column software switch at location 49 1 65 ($ COO D) .

6. BASIC programs that use 80 -col u m n firmware should P O K E

location 3 6 with tab locations rather than attem pting t o do "comma
tabbing . "

7. Any program that uses 80 -column firmware can not also display
flashing characters . F lashing characters are not available in the
alternate character set, which is the set the 80 -col u m n firmware
uses .

Peripheral Card Firmware

Any peripheral card that is to work on the Apple l i e should have firmware
that takes into account the protocols of BAS I C , Pascal 1 .0 , and Pascal
1 . 1 . Pascal 1 . 1 protocols were purposely made flexible enough to meet
the req uirements of future versions of Pascal , extending the useful life of
peripheral card firmware .

These protocols are not unique to the Apple l i e , but rathe r are published
here to make it easier for peripheral firmware designers to find all
requirements in one place .

3
 BASIC Protocol
T h e BASIC protocol is very simple ; it requires that three entry points be
found at fixed locations for a card i n slot s:

Address Contains

$ C s00 initialization routine entry point

$ C s05 input routine entry point

$ C s07 output routine entry point

Pascal 1.0 Protocol

There are also three entry points for firmware cards under the Pascal
1 .0 protocol:

Address Contains

$ C 800 initialization routine entry point

$ C 84 D read routine entry point

$ C 9A A write routine entry point

N ew peripheral cards can be "accepted" into the Pascal 1 .0 system by

using these entry points, as well as having the values$3 8 at locatio n
$ c 5o s a n d$1 8 a t$ c 5 0 7 ( s e e Device I D discussion below) .

Pas cal 1 1 Protocol

Pascal 1 . 1 has a more flexible setup and supports more i n put/output
functions than BASIC or Pascal 1 .0. It makes i n d i rect calls to the
firmware i n a ( new) peripheral card through addresses i n a branch table
i n the card 's firmware . It also has facilities for uniq uely identifying new
peripheral I/O devices .

The 1/0 routine entry point branch table is located n ear the b e g i n n i n g of
the $ c 50 o address space ( s being the slot n u m be r where the p e ri p h e ral
card is i n stalled ) . This space was chosen i nstead of the$ c 8 o o spac e ,
since u n d e r BASIC protocol the$ c 5o o space i s required , w h i l e the
$ c 8 o o space is optional.

4
The branch table locations that Pascal 1 . 1 uses are:

Address Contains

$ C s0 D initialization routine offset (required)

$ C s0 E read routine offset (required)

# C sO F write routine offset (required)

$ c s1 0 status routine offset (required)

$ C s1 1 $0 0 if optional offsets follow; non-zero if not

$ C s1 2 control routine offset (optional)

$ C s1 3 interrupt handling routine offset (optional)

Notice that $ c s 11 contain s $o o only if the control and i nterrupt

han d l i n g routin es are supported by the firmware. Apple II Pascal 1 0 .

and 1 . 1 do not support control and i n terrupt requests, but s u c h

requests m a y be i m p l e m e nted i n f u t u r e versions of the Pascal B I OS
and other future Apple I I operati n g system s .

H e re are t h e entry point addresses, a n d the contents o f the 6502

registers on entry to and on exit from Pascal 1 . 1 1 /0 routi n e s:

Addr. Offset for X Register Y Register A Register

$ C s0 D Initialization
On entry .$ c s $ sO
On exit error code (unchanged) (unchanged)

$ C s0 E Read
On entry $ Cs $ sO
On exit error code (unchanged) character read

$ C s0 F Write
On entry $ Cs $ sO char. to write
On exit error code (unchanged) (unchanged)

Status $ c s1 0
On entry $ Cs $ sO request ( 0 or 1 )
On exit error code (changed) (unchanged)

Notes: Request code 0 means, "Are you ready to accept output?" Request
code 1 means, "Do you have input ready?" On exit, the reply to the status
request is in the carry bit: carry clear means "No"; carry set means "Yes."

5
 Pascal 1 . 1 uses four firmware bytes to identify the peripheral card. Both
the identifying bytes and the branch table are n ear the b e g i n n i n g of the
$ c s o o ROM space . The identifiers are listed in the follow i n g tab l e .

Address Value

$ C s05 $3 8 (standard BASIC requirement)

$ C s07 $1 8 (standard BASIC requirement)

$ C s0B $01 (generic signature of firmware cards)

$ C s0 C $ c i (device signature; see below)

The first digit, c, of the device signature byte identifies the device class.

Digit Class

$0 reserved

$1 printer

$2 joystick or other X- Y input device

$3 serial or parallel 1/0 card

$4 modem

$5 sound or speech device

$6 clock

$7 mass storage device

$8 80-column card

$9 network or bus interface

$A special purpose (none of the above)

$B-F reserved for future expansion

The second digit, i, of the device sig nature byte is a u n i q u e identifier for
the card, assigned by Apple Techn ical Support. For example, the
Apple lie 80 -Column Text Card has a device sig nature of $88.

Although version 1 . 1 of Pascal i g nores the device s i g n ature,

appl ications prog rams can use them to identify specific device s .

6
Hardware
The Apple l i e Reference Manual specifies the overall physical and
electrical characteristics of peripheral cards disigned for use with the
Apple lie compute r . I n addition to these requirements, some d etailed
guidelines apply:

1. To maintain a consistent installation procedure as well as avoid

interference with adjacent cards, always design cards so their
component sides face away from the power supply case .

2. Avoid designs that require connection to c h i p sockets on the main

circuit board, as future revisions to the board may make such cards
obsolete .

3. Do not require that a card be installed i n slot 3 if its intended

application can involve a text or video card i n the A U X C O N N ECTOR
slot.

4. Cards should not dissipate more than the amount of power specified
i n Chapter 7 of the Apple lie Reference Man ual .

5. Cables should use 9-pin or 25 -pin " DB" style connectors . The four
1 9-pin openings ( 1 through 4 ) on the back panel are reserved for
use with disk drives.

6. I nternal cables should preferably con nect to the keyboard end of

the card. This g ives the user more freedom i n selecti n g a slot to
install the card . It also alleviates strai n and bending on the cable .

7. Cards that have firmware on them should be identifiable accord ing

to the protocols outlined i n the F i rmware section preceding th i s .

7
Part II
User Interface Guidelines
Introduction
The following gu idelines and comments have been written for a diverse
audience .

As a professional buyer and sellers of software, you can gain an insight

into the elements that will make a program most useable to your
customers . While this document is aimed pri marily at prog ram
designers, you can pick up a "feel" for interface desig n . Is your d ifficulty
in using a program because the designer failed to make it "friendly, " or is
it only because you lack specific experience in the subject of the
program? Are the customers who will be buying the prog ram from you
well versed in that subject area? If not, they will have the same trouble
you are having.

As a novice program mer, you will find not only specific information on
how to implement certain guidel i nes, but a fair amount of philosophy of
design that should be of help i n areas of design not covered.

The expert program designer may skim past what has become the
obvious-don ' t just g ive error n u m bers i nstead of m ean ingful error
messages-to find standard layouts and key-function definitions for
i n puts, men us, command structures, and instruction page s .

You can explore additional BASIC basics o f h uman inte rface design for
the Apple in

Apple Backpack, H umanized Prog ramm i n g i n BASIC, by Scot Kam ins,

Ph . D ., published by Byte Books of McG raw- H i l l .

There are two primary functions o f a good h uman i nterface design : make
the product easy to learn, and make it easy to use . We all know that our
customers can learn to use our programs faste r if they look and act l i ke
other prog rams with which the customer is already fam iliar.

When the Apple I I and Apple Ill series com puters first came on the
market, software developers experim ented with a wide variety of
interface designs. Some were good, some were bad. All were
somewhat hard to learn, because all were u n i q u e . As time went on,
though, the natural personalities of the keyboards, displays, and
computers led to a remarkable similarity of approach to certai n basic
problems of ease of use.

This document is drawn from applications prog rams written both within
and without Appl e . It further relies on human inte rface research projects
inside Apple and standards developed by independent software
developers .

9
 We are not i n any sense trying to dictate what program designers shall
and shall not do within their own programs . Each prog ram has its own
n eeds; each guideline will have its own exception s . Programs should not
be judged by whether they adhere to each specific g u i d e l i n e presented
i n this man ual ; they should be judged by whether they are reasonable to
learn , functional to use , and whether they get the job done .

What w e are offering i s a set of i nterface guidelines and standard key

defin itions to which we and many independent developers are
comm itted , guidelines and definitions your customers will know and be
comfortable with. We are releasing trai n i n g material that will prepare your
customers to use programs that work i n the manner described i n this
document.

Good Human Interlaces:

So Often Elusive
The hu man interface of a prog ram is as vital to its success in the
marketplace as its accuracy in performing its task. An otherwise well
designed , powerful piece of software or hardware is n early useless if it is
poorly human engineered . As Dr. F rank G ilbreth , the father of tim e and
motion study sai d : "It is cheaper and more productive to design
machines to fit men rather than to force men to fit machines . "

H u man interface design should come into play from the very beg i n n i n g.
A good design is no mean task: expect to expend a g reat deal of design
and programming effort toward a smooth interface . F o r most prog rams
with a good human interfac e , the design of that interface consumes
more design time, is more prone to bugs , and is harder to test than any
other part.

Apple is in the process of making available a n u m ber of packages of

routines that should make this task easie r . Wi thin the packages are the
menu drivers and input routines described i n this document. Exact
publication times are being set as this docu ment goes to press .

A Planning and Testing Methodology

ttte Prof. .e
I n order to properly address the needs of the users , you m ust first k now
who they are and what their needs are . Software design should begin
with a user-profile study. This study should cover the following three
phases :

10
1. Select the target audience . Begin your h uman i nterface design by
identifying your target audience . Are you writing for businesspeople
or children? Will your audience consist of people relaxin g at home or
accountants under severe time constraints?

2. Ascertain the level and lim itations of their pre-existing knowled g e .

You should have a n understanding o f h o w much t h e target users
know about:

A. using the Apple omputer

B. the general subject matter your prog ram deals with .

3. Identify their needs. Once you have an understan d i n g of the

knowledge and lim itations of the users, you can then figure out what
types of information and level of support the the program will have to
supply.

F ig u res 1 and 2 are mythical exam ples of two possible user- profiles for
prog rams that fill the exact same function : tax plan n i n g . Even thoug h the
task performed , the formulas used, the raw data required are identical ,
the programs that would result from the two user-profiles might bear little
external resem blance .

The " research " quoted in the exam ples is ficticious-do not start
writing a tax planner based on it. (The "case histories" in this document
are real ; the samples of display and document designs are fictitious . )

Carrying out an early investigation such as the ones above requires a

m i n i m u m of time and can save you man-months of work later on . The
reports need not be works of art ; it is only i m portant that every m e m b e r
of t h e d e s i g n team have a clear picture of who the a u d i e n c e f o r this
product will be.

Make sure you consider all your users :

I n a data- base program recently developed for a com puter with larg e
mass storage, no effort was spared in making every section of the
prog ram as "friendly" as possible . When a particular task proved
somewhat difficult to learn or use, the task was reduced by picking up
bits and pieces of it within o ther tasks . The program slowly drifted
toward being consistently somewhat difficult to learn and use .

(Text conti n u e d after figures)

11
Figure 1 Big, Big B usiness Software Development Corporation

H ouston, Texas
"Get the Big, Big Solution to y our Little Old Problems"

Professional Tax Planner User Profile Study

July 17, 1983

User: CP A or Public Accountant

Anticipated knowledge of Apple computers: none. (The accountant

may well have purchased the system just because of our program.)

Assumed knowledge of subject matter: Expert

N eeds :

1. Staged learning curve. Must feel com f ortable in a

minimum time. Extended features can be picked up later.

2. Facility. Must be able to crea t e and edit scenarios

quickly.

3. Clear instructions and error messages. User may have

never touched a computer before. Help sho uld be aimed
toward problems in the use of the system, rather than
explanations of the difference between Short-term and
Long-term capital gains.

4. Professional appearance. Accountants will be using

this package not only to help their clients, b ut to
impress them. The v ocabulary used on the display and in
printed reports should be serious and professional. It
may contain accounting jargon in areas that will n ot
cause confusion to clients. The accountant must be
protected against embarrassing errors (and error
messages) ; he may have a client sitting beside him.

S. Supplementary Features: accountants surveyed currently

add or subtract amounts from the "accurate" figures
produced by tax planners. Such items as a rough
estimate of state tax liability may need to be figured
into reports. Provide this facility.

6. Accountants are habitual users of adding machines:

they may be expected to do all intermediate calculations
on their own adder. No calculator function need be
provided.

12
F igure 2 Aunt Treig' s Software a nd Snowshoe Company
Petersberg, Alaska
"We'll never leave you out in the cold"

Pers onal Tax Planner User Profile Study

December 2 1, 1982

User: John Q. Middle to Upper-income Public

Anticipated knowledge of Apple computers : owner with some

experience. (Research indicates that tax planning programs
do not stimulate an initial computer purchase: people who
already own the computer are huying the packages.)

Assumed knowledge of subject matter: None

Needs:

1. The prompting and documentation need to be tutorial:

the user must be guided into finding the necessary
information to enter into the program, carrying out the
kind of explorations with the program that will be most
beneficial, and then suggest where the user should go
from here.

2. Clear content verification and error messages.

"Unlikely" data should be confirmed by user. Help
should be aimed toward problems in understanding the
subject of taxes.

3. Appearance and use of accounting jargon.

Non-professionals will be using this package. The
vocabulary used on the display and in printed reports
s hould be non-intimidating and not filled with
accounting jargon.

4. User will probably use the program only a few times per
_
year. T here must be a minimum learning curve, eve n at
the expense of reduced power and fac.ility. A
menu-driven format should ce rt a inly be considered as a
first cut.

5. The user has to be asked for a lot of pre-computed

figures: use an expression-eva luator input to allow
them to add, subtra c t, multiply, and divide during
i np ut.

13
 The designers had never considered w ho their audience was beyond
their being "office workers, " but when problems showed u p d u r i n g
testin g, they sat down a n d did a u s e r profile. What t h e y fou n d was that
there would be three separate users of the system :

1. The data-entry persons . These folk would be proficient typists who

i n itially would be expected to enter a g reat d eal of pre-existin g
information . They might b e temporary help, or they m i g ht be people
who normally performed a different job. Their needs were for an
i nterface that is quick to learn and easy to use .

2. The decision makers . These people would be expected to d raw

information from the system, both by calling up data on the display
and by generating reports . They could be expected to be habitual
users of the system : they could handle a long but g e n tl e learn i n g
curve that would give them progressively more power.

3. The key operators . These people are the ones who, i n real life, read
the manuals. They can be expected to spend some tim e with the
system initially and can be expected to learn how to perform the
more technical operation and maintenance tasks of the syste m .

Once the users of the system were i dentified, once their i n d ividual
n eeds were identified, the designers were able to " u n balance" their
equally-difficult interface, so that each user had a level of difficulty
consistent with their skills and the amount of tim e they could spend
learni n g the syste m .

Once t h e users have been profiled a n d a prototype built, it is t i m e to

begin testin g .

H u man i nterfaces are not mad e ; they evolve . Software designers are
sim ply too close to their product, their computer, and have put u p with
the most abysmal i nterfaces themselves for too many years to be able to
outguess the naive user . Pr oducts m ust be repeatedly tested on "real
people " . (" Real people" means the target a udience : as soon as you find
yourself sitting in a meeting with other com puterists, all announcing what
users will or will not feel/thi n k/do, you are in trouble. Build the prototype
and find out. )

The job of the designer is to do her best to predict the response of the
user; the job of the user is to do just the opposite.

14
H u man interface testing is q uite different from the kin d of exhaustive
" boundary condition" testing used to uncover bugs . You should begin
testing as early as possible , using drafted friends, relatives , and new
em ployees , to uncover the really big holes i n your design . As you get
closer to a finished product, try it out on large r g roups d rawn from the
target population .

It is i m perative that the designers actually watch people use the

program . Do not just send o ff copies of the program and expect written
r esponses . G et the users and the designers i n a quiet room together.

Our testing m ethod is as follows . We set u p a room with five to six

computer system s . We schedule two to three g roups of five to six users
at a time to try out the systems (often without their knowing that it is the
software rather than the system that we are testi n g ) . We have two of the
designers i n the room . Any fewer , and they m iss a lot of what is going on .
Any more and the users feel as though there is always someone
breathing down their necks .

T h e i nitial ground rules are that no q uestions w i l l be answere d , a s b y the

time the formal testing beg i n s , we can supply a d raft of the man ual .
( Usually by the second group , some g larin g defects in the interface have
shown u p , and we have to g ive them help gettin g past t h e stu m bl i n g
blocks . )

Ninety-five percent o f the stumbling blocks are fou n d b y watc h i n g the

body language of the users . Watch for squinting eyes , h unched
shoulders , shaking heads, and deep, heart-felt s i g h s . When a user h its a
snag , he will assume it is "on account of he is not too bright" : he will not
report it; he will hide it. Make notes of each problem and where it
occurre d . Q u estion the users at the end of the session to explore why
the problems occurre d . Do not make assumptions about why a user
became confuse d . Ask him . You will often be surprised to learn what the
user thought the program was doing at the tim e h e got lost.

We have found that prepared questionnaires handed out at the e n d of a

session are of little val u e : you will seldom predict the problem areas
before testi n g , and users will lie to spare everyone's feeli n g s . ( I f you had
figured out the problem areas , you would have already fixed them . )

G e nerally, two o r three groups o n one occasion is more than sufficient:

patterns will emerge almost immediately. You should have at least one
more ban k of testing after any major revision; as the n ext exam ple
shows , one often jumps out of the frying pan , into the fire .

15
 The True Anecdote :

Herein follows a true anecdote that illustrates how d ifficult the most
simple human i nterface issue can be , and why thoro u g h testin g on real
people is so i m portant. (If you dislike true anecdote s , please skip ahead
to "Goals . " )

As we tune i n , the authors of APPLE PRESE NTS . . . APPLE , both of

whom pride themselves on clever interface desig n , have anguished for
hours over difficult passages in their program . It was to turn out their
guesses were quite accurate i n said difficult passages. It was the
sim plest question of all that caused all the problems . . .

Problem : i n APPLE PRESE NTS . . . A P P L E , a n I ntroduction to

the Apple l i e Compute r , the train i n g program for
teaching fundamentals of using the new Apple l i e
computer, find out i f the user is workin g with a color
monitor.
User profiles : new owner, customer i n a com puter store , or
member of a class learning to use Apple
com puters .

Test user customers in a com puter store , non-computerists

profiles : in a classroom environment, fri e n d s , and relatives .

First design : A color graphic would be d isplaye d .

Prompt: "Are you using a color T V on t h e Apple?"

Antici pated Those who were usin g a monochrome mon itor i n a

problem : classroom or computer store situation wouldn ' t
know whether t h e monitor was black a n d w hite o r
was color w i t h t h e color t u r n e d off .

First attempt: A color graphic was displaye d .

Prompt: "Is t h e picture above i n color?"
Failure rate : 25%

Reaso n : As antici pated , but incorrectly overco m e , those

seeing black and white thought their color m i g h t be
turned down . They didn't answer the q u estion
wron g ; they turned around and asked one of the
authors whether the mon itor i n q u estion was color
or not. A decision was made that the authors could
not be shipped with each disk.

16
Second attempt: A smaller g raphic with large-letter words in their
own vivid colors was substituted :
G R E E N BLUE ORANG E M AG ENTA
Prompt: "Are the words above in color?"
Failure rate: color TV users : none
black and white mon itor users: none
green-screen monitor users : 1 00%

Third attempt: The g raphic remained the same.

Prompt: "Are the words above in more than one color?"
Failure rate : color TV users: none
black and white monitor users : 20%
g reen-screen mon itor users : 50%

Reasons: the black and white monitor users who answered

incorrectly adm itted that they did so on p u rpos e .
( O u r methods f o r wri n g i n g t h e i r confessions shall
remain proprietary . ) 50% of the green-screen folk
considered that they were lookin g at both black and
g reen- two colors- and answered the q uestion
accordingly.

Fourth attempt: Same display of g raphic and colored text

Prompt: "Are the words above in several d ifferent colors?"
Failure rate : color TV users : none
b lack and white mon itor users : 20%
g reen-screen mon itor users : 25%

Reasons: By this tim e, the authors were prepared to supply

everyone who bought an Apple with a free color
monitor, just so we would not have to ask the
questio n . It turns out that around 20% of the people
were not really reading the q uestion . They were
responding to :

" Are the words above, several different colors?"

Fifth attempt: Same display of g raphic and colored text

Prompt: " Do the words above appear i n several d ifferent
colors?"
Failure rate: none.

17
 I n case it appears the authors were simply dull fellows, b e i t known that
this was a fully-interactive train i n g program i n excess of 1 OO K, and this
was the only i nterface issue that required more than one correctio n . It
clearly exemplifies how even the most careful designers can totally m iss
when g uessing at how users are going to respond .

Had the designers not tested the program, it is probable that dealers
would not have used the prog ram in their showrooms, as they would
have wearied of telling potential customers that they were/were not
using a color TV and that the APPLE PRESENTS . . . APPLE program was
being very stupid to ask the question like that. ( Potential custo m ers, of
course, wouldn't have fallen for such an explanation : they would have
known it was the computer that asked the question, and everyon e
knows that o n e should always b u y t h e computer that asks good
questions . )

I t is vital that programs and manuals b e tested early and often with users
from the target audience ; this testin g should be an inte gral part of any
testing plan . This testing seems like a lot of extra effort, but i n practice, it
really isn't, beyond the mechanical difficulties of getti n g you r equipment
and test group together. (Computer stores, colleges, and shopping
cent ers are often good random-testin g locations . ) The above testin g
cycles took only four days : t h e first two days were on-site, u s i n g n e w
Apple em ployees . Only two days of testing required a n y set- u p work at
all, and the overall improvement to the product was clearly worth the
effort .

Even if the interface had not changed at all, it would have been worth it
just to be able to ward off all the self- proclaimed experts with their ( day
after-going-to-production) comments of " Boy, I sure wou l d n ' t have done
it that way. A lot of people out there are gonna have trouble . ' ' What joy to
turn to such people and announce with a clear conscience, "Well, we
tried it out on 1 09 people, and they all sailed throug h with flyin g colors. "

18
Goals
Simplicity
User interaction should be simple and easy to remember. Spend the
necessary tim e to design a user interface that presents the best tradeoff
between alternate design issues.

Once the user has become basically fam iliar with the h u m an interface, if
she guesses at an un known response, she should be correct 95% of
the time .

Simplici ty is discussed in detail in the next section, G en e ral Program

Structure .

BASIC: When a package contains several programs on a diskette, the

programs should always be selectable by the user via a menu display. The
user should not have to RUN (or worse, BRUN) individual programs in
immediate mode to get the package to function. Each program should end
by causing a "menu" program to be run, which should provide the
appropriate menu display. The menu program should be a simple program
which displays a menu of all programs to which the user will be given direct
access, and stores information on the environment in which it runs; for
example, it can set any HIMEM: or LOMEM: required by a program on its
menu. An example of this is INDEX on THE SHELL GAMES diskette.

Consistency
All programs written for a g iven computer should have as g reat a
commonality as is practical. The purpose of these g uidelines and
standards is to achieve a level of consistency across all products
designed to run on the Apple, a level that will make learning your product
easier, but not be so rigid as to stifle your ability to create the specific
h uman interface best suited to your particular application.

All programs produced by a g iven software house should perform the

same function in the same way . The same key sequence m ust not do the
opposite thing in different products ( E= edit, E= era dicate) . M any
software houses have their own guidelines, guidelines from which we
drew in preparing this document. These individual g u i de l i n es tend to
outline in far g reater detail the program "personality" that the software
house wants to project. If you have not yet put together such a
document, may we suggest you do so. It is a very effective way to
eliminate those interface battles that tend to occur about three days
before release to production-or three days after.

All software should be self-consistent: menu formats should be identical.

If G ET or READ KEY is used for one input, it should be used for all inputs.
If the LEFT-AR ROW key deletes c haracters in one part of the prog ram, it

19
 should delete characters in all parts of the program . If you are workin g on
a large project, be sure to spend enough time i n team meeti n g s being
sure that everyone is on the same track-all too often the three or four
sections Qf a program end up with an entirely different "feel . " At the
same tim e . avoid rigidity : hu man interfaces m ust be tested on real
peopl e . The agreed-upon interface at the beg i n n i n g will undoubtedly
need chang i n g . once you try it out on real people .

The user should b e able to perform the desired task in a s little

( perceived) time as possible, with the m i n i m u m ( perceived) complexity .
Match the program to the skill level of the use r . If you are doing a pricin g
program for a shopkeeper . do not ask her what her h istoric elasticity of
demand has been without letting her know what it is and g iving her the
tools to estimate it. (Also, the question may be u n necessary : the fact
that you asked it in a similar program you wrote for a Fortun e 500
com pany is no reason to ask it of a shopkeeper . )

Self-teaching
Often there is a trade-off between ease of learning and ease of use .
Carefully balance your decisions: if the program is too difficult to learn,
salespeople will not learn it and . thus. not sell it. If endless instructions
and volum inous menus make it slow and cum bersome to use . people will
get frustrated and tell their friends not to buy it.

You will find a n umber of guidelines devoted to overco m i n g this problem .

Both syntactic and content help should be available at the point at which
it is needed; designers are successfully doing that without encumber i n g
t h e experienced user. See : H e l p and Menu . M a n y desig n e rs have
sucessfully created a multi-tiered interface . See: Novice/expert modes .

Speedinec:;s
Actual speed of operations is im portant. but perceived speed is even
more im portant. It may seem im portant to conserve keystrokes . but it is
more im portant to conserve "brain strokes" and design the interface so
that there is a natural flow . A more i m portant goal is to reduce the amount
of unproductive tim e . which is time spent deciding how to perform the
desired task rather than time spent performing the task . This concern
should permeate the entire design process .

React to user's in put immediately. A user will interpret any d elay of more
than a few tenths of a second after he has pressed R ETU R N to m ean

20
that either the program or the user has made an error. If you need to
make a computation , first acknowledge that you have accepted the
input.

In training or educational software , it is doubly i m portant to react

immediately to test questions. The g reatest retention of knowledge
occurs when response occurs either with i n one second or not until the
end of the entire test. Apparently , waitin g five to ten seconds for a
correct/not correct judgement is so frustratin g that people lose
i nvolvement with what is going on.

Minimum Strain on /'Pe Users Me ..,.V

,.

Prog rams that are not used literally ev ery single day will be forgotten .
Users will not remember command words , the names of their files , nor
the fact that you are acceptin g data not with R ETU R N, b ut with CTRL-V.
(Violet was the name of your very first computer science teacher. )

Com puters are notoriously good at remembering the above type of

i nformation. Share it with your user: make sure the i nformation needed is
available where and when needed.

1-lonsty
Do not lie to your users . Do not say , " File loaded" when the file is not
loaded , only the name of the file has been " loaded , " whatever that
m eans.

General Program Structure

The contemporary microcomputer user may have no pr evious

experience with a prog ram . Therefore , a significant fraction of the
programming effort must be dedicated to the creation of an intuitively

21
 natural human interface. The program m ust, in the s i m plest way
possible , anticipate the user's questions and needs and be prepared to
answer and fill them the moment they arise.

There are two important principles being followed in the m ost successful
h u man interfaces designs.

Keep It Simple
The external appearance of the program is as simple as possible. The
user does not get lost within a maze of branches. (You may safely
assume that the first-time user has not read the man ual . )

The number o f screens and menus i s kept to a m i n i m u m . The ALF'M

m usic editor and VisiCalc'M are excellent exam ples of this concept.

Displays are kept clean and simple . Q uestions posed are clear and free
of am biguity .

Fluidity : Movement within t h e prog ram is easy a n d flu i d . T h e structure i s

simple en ough to allow t h e user to move from place t o place without
becoming confused.

Tools: The user is provided with the necessary tools to work with the
program . For exam ple, in a personal finance program, an input
requesting ann ual rent should allow an answer such as 435.00 * 12 or
435.00 X 12, and not expect the user to work out the answer i n his or
her head . If a file name must be selected from the disk, those file names
are either displayed or available for display .

Make It Familiar and Intuitive

Everything the program expects the user to do is either fam iliar or feels
intuitively right. The user should feel comfortable with i n the program and
the prog ram should be supportive, responding to the user's best g u ess
of the right thing to do at any one moment. Everything i n this document
really leads toward an intuitively correct program . But matters of intuition
can not be thoroughly dissected : the ultimate test lies with whether a
n ew user can feel master of the program with i n a very short time, or
whether he will simply flounder around, trying to figure out what the
program wants and why.

Special Key Functions Are Consistent

If a user wishes to complete an input, she knows to always press the
R E T u R N key . E s c A P E always al lows the user to escape back
whence she cam e .

22
Anticipation
The program antici pates as m u c h as poss i b l e the n e e d s
a n d questions o f the u s e r a n d is prepared t o han d l e them a s they arise.

Intelligence
The program does not ask for u n n ecessary data, data
which can be derived from information already at hand, o r data already
asked for and received before .

Confirmation
The program tries to prevent catastrophic errors . If the user commands
that a 1 OO K text file be deleted, the program should require cogn i zant
confirmation :
Are you sure you want to destroy 5 days' work? Type DESTROY 5
DAYS' WOR K to confirm .
If the user commands that a new file be saved under a name already
being used for a 1 OO K text file, the program will announce that saving
the file under this name will result in the destruction of the original file,
and then present a confirmation question similar to the one above if the
user says to save the file under the duplicate name anyway .

Tree Structures
The tree structure of a program is designed to feel natural to a user, not
the program mer. For exampl e, one could design a prog ram which will
both create and play music. Saving created music and load i n g that m usic
for later playing are hig hly sim ilar programm i n g tasks and can q u ite
possibly be done using the same basic subrouti n e s . But w h i l e it is
structurally logical to share code between them, it is intu itively wrong to
dump the two options adjacent to each other on a m en u . Savi n g should
be grouped with other m usic-creation options ; load i n g with both creation
(for editing), and playing.

Novice/Expert Modes
The first time a user runs a prog ram he has qu ite different needs from the
tenth time he uses it. I n the begi n n i n g, he needs as much information
presented as possible so that he can use the program with a m i n i m u m of
learning . Later on, with a program used habitually, he wants speed and
sim plicity . H e wants only i nformation pertinent to the specific task being
carried out, not a lot of instructions on how to d elete an incorrect
response.

Most large programs now have some sort of utility/confi g u ration section .
The config u ration sections often enable the user to select date and time
formats, color vs . black and white, and whether or not to have sou n d . I n that

23
 section , you can also enable the user to select a skill leve l . The rest of
the program can then use the resulting flag , when set to expert, to
simplify verbiage and perhaps enable more flexible bran c h i n g with i n the
prog ram-branching that would serve to get the novice into trouble but
g ives the expert the added flexibility she needs .

The skill level selection could be more sophisticated , perhaps with more
than two le vels, perhaps based on the type of user. For exam ple , a
single tax planner program might better bridge the gap between
accountant and Apple owner if the accountant could select, " Expert at
taxes , Novice at Apple" and the Apple owner could select " N ovice at
taxes, Expert at Apple " . (The possible combinations and perm utations
are truly boggling . )

Ending

T h e user is given a way out of the program . Even if your program is on a

copy- protected disk and there really is no way out, g ive the user an E n d
option a n d t h e n tell him that he may n o w insert another d i s k and press
R ETU R N , or whatever . Users feel positively trapped by programs with
seemingly no end ; they forget that the power switch solves all .

BASIC programs should also reset and clear H i res screens and revert
to normal text condition upon a normal exit i n order to prevent
interference with other unrelated programs .

T h e programs should also reset other system parameters t o customary

settings.

The balance of this document presents more concrete g u idelines for

specific prog ram areas .

Input

Two major languages native to the Apple I I and Apple Ill series
computers are BASIC and Pascal . Each has an input routin e as part of
the languag e . These in put routines are used i n many program s , and you r
customers have become fam iliar with the m . However , they are not
particularly well suited to most professional applications. As a result, in
the past, each software engineer has created her own routi n e , usually a
variation of one or the other "standard " i n put routi n e . The direction of
this creative technology has been toward more sophisticated i n put
schemes which allow insertion and deletion of characters . This
proliferation of in puts , each with its attendant cursor and special keys ,
has left the poor user rather bewildered .

24
 Enter The Three Cursors : New Apple owners are being trained to
recognize and use three different in puts : BASIC's, Pascal's, and the
n ew insert/delete i nput. They are being trained that they can tell what
i n put they are faced with by the kind of cursor presented .

BASIC uses the blinking box cursor which overlays a character . Pascal
uses the solid box cursor which overlays a character . The new input
uses a blinking underline cursor which lies between c haracters .

Of all the standards being presented, this is the most important : The user
should be able to tell the rules of the i nput from the kind of cursor being
displaye d . If everyone conforms to the use of the proper cursor for each
personality of i n put (defined further below), Apple users will be relieved
of a major source of frustration . It is really hard to concentrate on learn ing
to do ellipsoid analysis of pork belly futures when you can 't figure out
what key to press to correct a typo .

If you need additional features, then keep the original cursor and enable
the original features : make your input scheme a superset of the origi nal .
If you need to use an entirely different kin d of i n put scheme, please
select a different cursor and train your users to recognize it as yet
another entity .

The (Apple II BASIC) Blinking- box Cursor

Computer Move left Move right Insert Delete Accept Cancel

Apple ll's LE F T A R R O W RIG H T A R R O W *

RETURN C O N T R OL- X

Apple Ill's LE F T A R R O W RIG H T A R R O W RETURN C O N T R OL- X

*A user can both insert and delete within a BASIC input line using E s c A P E -cursor keys. As a practical matter, however, few other than
experienced BASIC programmers can actually do so with any facility, as the screen ceases to reflect what the character-input buffer
is actually holding.

The (Pascal) Solid-box Cursor

Computer Move left or right Insert Delete-from-end Accept Cancel

Apple ll's LE F T A R R O W RETURN C O N T R OL - X

Apple Ill's LE F T A R R O W RETURN C O N T R OL- X

25
 The
Apple II Series

Keystroke Editing Operation

Necessary :

LE FT-ARROW moves cursor left within input line.

R I GHT-ARROW moves cursor right within input line.

C T R L- D deletes character to the left of the cursor - Apple I I & I I + .

DE LETE deletes character to the left of the cursor - Apple l i e .

RETURN accepts entire response , regardless o f current cursor position.

C T R L-B has no effect on a display with a single input. On a multiple- input

display (see next section) , c T R L - B accepts entire response,
moving user back to previous input.

Useful if implementation language allows sufficient speed :

C T R L-X deletes all characters on the input line.

CTRL-Y deletes all chars from present cursor position to end of line.

C T R L- R recalls display of default response . If no default, then it acts the

same as c T R L - X .

Optional

CTR L-P Prints the contents of the display on the default printer.

Notes

Because this i nput is new to Apple I I and Apple I I + users, it is

particularly in portant that you expressly state on the display that c T R L - o
is used to delete characters . ( Apple l i e users have b e e n trai n e d how to
use this i n put on the APPLE P R E S E NTS. .. A P P L E d i s kette , but a
reminder to use the o E L E T E key would be h e l pfu l . )

Typ i n g any printing character will automatically i nsert that c haracter

i nto the input line at the current cursor position .

Pressing R E T u R N with the cu rsor anywhere within the i n put l i n e w i l l

accept the entire i n p u t .

Defau lt responses a r e displayed w i t h the c u rsor a t the e n d of the

response .

RETURN will accept that response .

LEFT-ARROW will move cursor back into the default response, enabling the
user to edit it.

R I GHT-ARROW will signal that you wish to append material to the response.

C T R L- D (Apple II & II + ) will delete a single character from the end of a

response and signal that you wish to edit the response.

26
DE LETE (Apple l ie) will delete a single character from the end of the
response and signal that you wish to edit the response.

Pressing any other key will clear the d efault response and begin a new
response in its place .

Apple Ill Series

Keystroke Editing Operation

Necessary:

LE FT-ARROW moves cursor left within input line.

R I GHT-ARROW moves cursor right within input line.

Either:

C T R L- S P A C E ,
C T R L- LE F T-
A R R 0 W , or D E L E T E will delete the character to the left of the cursor.

Either:

C T R L- R I G HT
A R R O W or
C T R L- D E LETE will delete the character to the right of the cursor.

RETURN accepts entire response , regardless of current cursor position.

C T R L-B has no effect on a display with a single input. On a multiple-input

display (see next section), c T R L - R E T u R N accepts entire
response, moving user back to previous input. Programs often
use

C T R L-RETURN in addition to c T R L - B for accept and move back c T R L

R E T u R N is indistinguishable from c T R L - M , or c T R L
whatever character-your-user-has-defined -to-be-in-M 's
standard-keyboard-position Please take this potential risk into
account before enabling c T R L - R E T u R N as well as c T R L - B .

C T R L- E deletes (erases) all characters on the input line.

C T R L-K deletes all chars from present cursor position to end of line .

C T R L-U (Un-do) recalls display of default response. If no default, then it

acts the same as c T R L - E .

Optional:

CTR L-P Prints the contents of tl<le display on the default printer.

Notes

Typing any printing character will automatically i nsert that character into
the input line at the current cursor position .

Pressing R E T u R N with the cursor anywhere with i n the i n p u t l i n e w i l l

accept the e n t i r e i n p u t .

27
 Default responses are displayed with the c u rsor at the e n d of the
response.

RETURN will accept that response.

LE FT-ARROW will move cursor back into the default response, enabling the
user to edit it .

R I GHT-ARROW will signal that you wish to append material to the response.
C T R L- S P A C E
or D E L E T E will delete a single character from the end of a response and
signal that you wish to edit the response.

Using the New Input on an Apple II or Apple Ill Series Computer

The program input statement asks the user for information by d isplay i n g
a verbal prompt. Prom pts s h o u l d terminate i n a colon ( : ) or g reater-than
sign ( ) ) if a statement, a question-mark (?) if a q uestion . The prompt is
followed by 2 spaces on an 80 -column display, 1 space on a 40 -col u m n
d isplay .

A default answer may be displayed , with the cursor followin g , in which

no field length is denoted . If there is no d efault response offered , o r the
d efauit is rejected by the user, the program can display a finite input field
with a series of periods (standard character set) or " ghost" underlines
( h i- res character set) . The latter character is essentially a shorte n e d
u n d e r l i n e with every other d o t turned off .

The specification of the n u m ber of spaces between the pro m pt and the
i n put field is quite im portant : users can become confused as to w h e re
their answer begins. If all programs adhere to one space with 40 col u m n
displays , 2 spaces with 80 col u m n displays , t h e users w i l l know whether
they have i nadvertently typed a leading space or not. ( As a separate
issue , leading and trailing spaces should be routinely stripped off , u nless
they are specifically needed . )

Keystroke errors are best trapped immediately : i f you are acceptin g a

decimal number, do not accept a letter such as "A" or " B " .

Here i s the exam ple o f the input which i s taught on APPLE

P R ESENTS . . . APPLE for the Apple l i e :

What i s a " drift"?

) A who l e L ot of cat t le_

28
(Consider the underline to be blinking - the printer was not able to q u ite
capture the effect. ) The problem presented is to chan g e the answer to
read :

) A h e rd of c a t t l e

To edit the response, the user first moves back to the e n d of the word
"lot, " using the L E F T A R R o w . It looks l i ke this :

) A who le lot of catt l -e

) A who le lot of catt- le

) A who le lot of cat_t le

) A w h o l e l o t o f c a -t t l e

) A who le lot of c_att le

) A who le lot of _catt le

) A who le lot of_ catt le

) A who le lot o_f catt le

) A who le lot _of catt le

) A who le lot- of catt le

The user is next instructed to press the D E L E T E key several times , until
the words "whole lot" have been d e l eted :

) A - of catt le

N ext , the user types the word " h e rd " :

) A h- of catt le

) A he_ of catt le

) A her_ of catt le

) A he rd- of catt le

29
 Finally, the user can press R E T u R N to accept the entire response :

) A herd of catt l e

C ursor Movement with no Action Taken

Someti m es programs such as word processors require pure c u rsor

movement with no action take n . The standard keys i n such cases are as
follows :

Keys for up . down , left, and right motion :

Apple II and Apple II Plus:

l = up
J = left K = right
M = down

These keys are often prefixed with an ESCA P E .

Apple l i e : t h e four arrow keys

Apple Ill: the four arrow keys

Keys for vertical, horizontal , and diagonal

motion :

Apple II , Apple II Plus , and Apple lie:

U = up , left l = up O = up , right
J = left K = right
N = down , left M = down , = down, right

These keys are often prefixed with an ESCA P E .

Apple Ill:

Full cursor movement on the Apple /// is

done using the numeric keypad :

7 = up, left 8 = up 9 = up , right

4 = 1eft 6 = right
1 = d own , left 2 = down 3 = down , right

In the olden days of com puters, one typed a command to a com p uter
onto a punched card . One then walked down the hall to the computer
room, left said card, and returned some hours later to find that the
command was syntactically incorrect. Later , time-sharin g changed all
that. Now one could type i n the command, then press a single key called

30
R E T u R N which would send the command down the hal l . Soon ( 1 5
seconds or so later) the computer would announce the command was
syntactically incorrect.

Many microcom puter programs sti ll wait aro u n d until the user has made
a thorough fool of h i mself and pressed R E T u R N before s e n d i n g the
resu lts "down the hall " to the prog ram unit w h i c h does keyword
matc h i n g. This u n necessary waste of process i n g ti m e and power is
i n herent i n the built-in i n put routi nes of the languages which have been
ported over to m i c ros from time-share systems. Since w e are g e n e rally
su pplanti ng those old routi nes with the new b l i n ki n g - u nd e r l i n e routi n e ,
which is accessible and can be taken apart , this waste n e e d n o t go o n.

Keyword matc h i n g is used i n prog rams which are c o m m a n d - d riven and

programs with l ists , such as file names , from which a user m ust select
by typ i n g i n the name of the selection. Ofte n , the h u m an interface is
rather sparse :

Command Word? _ . . . . . . . . . . .

File Name? _ . . . . . . . . . . . . . . .

Enter command and com man d-object:

o r , even more simply, (for the prog ram m e r )

Command-d riven programs offer a speed and flexibil ity not g e n e rally
attainable i n a m e n u - driven prog ram . They also typically offer a m u c h
steeper learn i n g cu rve-so debilitating a l earn i n g c u rve that
salespeople will often avoid selling a comman d - d riven prog ram
because of the time and practice required for them to g ive even a
r u d i m entary demonstration. Resu lt? Lost sales .

I n order to type a command or list selection without prompti n g , the user

m ust learn what words he can type at any one point i n the program. This
learning problem can be overcom e i n a straightforward man n e r by
displaying a list of all options then available. Typically, this can be done
by creating a dipplay similar to the standard m e n u format , with the center
region devoted to the list of words.

31
 Com modity Analyzer Bel l y Processes Pork Bel l i es

Commands Inventory Types :

display complete bel lies

graph partial bel lies

compute dancing bellies

buy

sell

eat

delete
Type your instruction and press RETU R N : _

Options: E s c A P E to leave 0 P E N - A P P L E - ? for help

As the available options chan g e , so do the options displayed . Thus, the

user knows at every point exactly what she can select. (The display of
command words could be made optional through the novice/expert flag ;
variable lists of words, such as file names, should always be visible . )

A second , more subtle learning problem m ust b e handled a different

way : Typically, a command word system will allow abreviations : why
make the user type i n "display dancing bellies" when " d i d " is all that is
requ i red to make the user's intentions clear? ( Display and Delete both
start with d. Once the i is added , display is the only possible answer. The
only command-object that currently starts with a d is "dancing bellies . "
Thus, the user's mean i n g i s not am biguous.

Usually the user has either had to look u p abbreviations of command

words i n the manual , or discover them by trial and error. Words from l ists
such as current file names have sim ply had to be typed out completely,
with no abbreviations accepted . The Disambiguator changes all that.

The algorithm for figuring out at what point the user has typed e n o u g h so
that an answer is unique ( not ambiguous) is really q u ite s i m p l e : on each
keystroke , the list of possible words is scann e d for a matc h - u p of as
many letters have been typed so far. As soon as only one match can be
fou n d , the word has been found and can be completed by the program .
I n the above exam p l e , the sequence would look l i ke this :

Type your instruction and press R E T u R N .

D-

No unique match is found ( both delete and display matc h ) so the input
only echos the user's character .

32
Type your instruction and press R E T u R N .
DI-sp lay

User's response is no longer am biguous: the program supplies the

remaining characters in the opposite case from that the user is typi n g.
(An alternate character set can be used when the environment permits,
so that the user can type both uppercase and lowercase c haracters. )

Type your i nstruction and press R E T u R N .

DIS-p lay

The user has not noticed that the computer has made a match, which
happens often with a touch-typist. There is no penalty : the new
character is echoed and the prog ram now supplies j ust that portion of
the command word still remai n i n g .

Type your i nstruction a n d press R E T u R N .

D I S P LAY -

The user has noticed that the answer has been fou n d and has pressed
the terminating character, i n this case a space. The prog ram completes
the word, using the case that the user has been typi n g and adds the
space to the end .

Type your instruction and press R E T u R N .

D I S P LAY D_anc i ng be l l i es

As soon as the " D " in "dancing bellies" has been typed, the remain d e r of
the phrase becomes clear.

Type your instruction and press R E T u R N .

D I S P LAY DAN C I N G B E L L I ES

The user term inates the i n p u t with R E T u R N and the f u l l answer is

echoed and acted upon.

The Disam big uator i n p u t has been used in a n u m be r of programs over

the last two years : it has proven to be q u ite successful . It l ets people
get used to abbreviations at their own speed, without t h e i r hav i n g to
look up anyth i n g or get yelled at by the computer for u s i n g the wrong
abbreviation, yet it accomplishes this with no penalty to the to u c h
typist who is j u s t a s h a p p y pou n d i n g out the entire word . As a f r i n g e
benefit, it s p e e d s up the prog ram 's response ti m e : w h e n the user
presses R E T u R N , the prog ram already knows what the i n struction is
and that it is legal .

33
 Pascal programs han d l i n g l ists of u p to thirty words i n any o n e context
have been i m plem ented with this routi n e in Pascal . Pascal programs
with very long l i sts or any BASIC prog rams need the routi n e to be
i m plemented i n native cod e .

The Disam biguator algorithm is j u s t an exam ple o f the ki n d o f

p rocessing that can go on actively d u r i n g the user's i n p u t t o m a k e t h e
u s e r ' s l i f e a little eas i e r . T h e r e is no l o n g e r a n y tec h n i cal reason f o r
prog rams t o stand by while users flo u n d e r , waiti n g t o pounce o n t h e m
w h e n t h e y press R E T U R N .

The user can control the movement from one display to the n ext by
pressing the R E T u R N key (or, optionally but consiste n tly , s P A c E bar ) .
H e is i nformed by a m essage such as , " Press the R E T u R N key to go o n
t o the m e n u . " on t h e bottom l i n e o f the screen . ( De lay l o o p s a r e diff ic u l t
t o j u d g e a s t o the p r o p e r d u ration , and b e c o m e somewhat i n s u l t i n g to
the i ntelligence of the user . ) The actual prompt m essag e s h o u l d give
some indication as to what w i l l happen n ext , rather than s i m p l y say i n g
" Press R E T u R N t o conti n ue . "

The educational software com m u n ity has pretty m u c h s e lected

s P A c E bar i nstead of R E T u R N to control move m e n t : c h i l d re n were
fo und to occasionally press R E s E T by accident on the older Apple l l ' s
and Apple I I Plusse s . Please b e consistent i n your choice o f R E T u R N o r
s P A c E bar , not only within a g iven prog ram , b u t across your c o m p l ete
p roduct l i n e .

D o n o t tell t h e u s e r t o ' ' press a n y key . " O n the A p p l e I I series

computers, you cannot read every key by itsel f : R E s E T , s H I F T ,
c o N T R o L . We have also found i n testing that new users , i n partic u l a r ,
pan i c when asked t o press any key . O v e r 80% of them w i l l turn aro u n d
and say , " but what key s h o u l d I press?" I n q uestio n i n g t h e m a b o u t t h i s
response, we discovered that t h e y a r e q u ite convinced that even
though the prompt implied all keys were O K to press , s o m e could b e
dan g erous . Of course , t h e y w e r e q u ite r i g h t .

While y o u should n o t t e l l t h e m t o press a n y key , y o u may , i n t h i s

specific case only, accept m o r e than the k e y specifie d . B o t h R E T u R N
and s P A c E bar should be accepted , even tho u g h o n l y o n e i s prom pted
for: users g row used to using one or the oth e r . You may optionally (and
only i n this specific case of using the key as a switc h ) want to accept
most keys , so that a user stri king out for s P A c E bar and pressi n g V by
accident will not be penalized . Do not accept E s c A P E i n stead of
R E T U R N or S P A C E bar .

34
Displays with several i nput statements:

Movement from in put to i nput is sequential : the user may m ove back
and forth but not randomly skip around .
Pressing the R E T u R N key automatically positions the user at the
n ext i n put statement.
Pressing c T R L - B automatically positions the user at the previous
i n put statement. The prior response to the previous i n p u t will be
displayed as that i n put's default.
The last i nput on the display will normally ask if the user has
completed all responses to her satisfaction .
No i nput will be accepted without the user explicitly termi nati n g it,
usually with R E T u R N or c T R L - B . The fact that the user has used u p
a l l t h e spaces avai lable i n t h e field should n o t automaticall y m ove
the user to the n ext question .

Errors

Error Trapping

I n most situations, user inputs must be checked for validity . Account

n u m bers, employee numbers, and dates are just a few exam ples of
items that should be checked to see if the data requested is on file or
plausible . Numeric inputs should be screened for values too small or too
large, if extreme values are invalid or potentially damagi n g to the
program . An error message line should be provided i n a consistent
location toward the bottom of the display .

Many types of errors can be circumvented through software design : If,

in testing, you find users repeatedly making the same kin d of errors,
change the software .

Make your program insensitive to upper/lower case when no d istinction

is necessary . Be particularly aware on Apple II programs : the new
Apple lie can generate lower-case characters . ( M ake sure you only

35
 transform characters : many of those obscure punctuation marks are
often-used special characters on foreign keyboards . )

Spaces should n ever b e significant. Users look u pon a space as a lack of

a character , not as a character . Strip leading and trail i n g spaces , and
intervening spaces too , when practical . For example , w h e n pro m pting
the user for the name of an existing file , should the user respond "door
bell " , first look for a literal matc h , then strip spaces , so that you can
match with the user's original , but now forgotte n , " doorbe l l " .

Likewise , do n o t refer t o "the R E T u R N character" , u n less y o u are

prepared to deliver an essay . Users steadfastly cling to their belief that
R E T u R N is an action , not a character .

D o n o t make commands position - d e p e n d e n t . F o r exam p l e , do n o t s e t

u p a stream o f " parameters" s u c h that if t h e u s e r wishes t o c h a n g e t h e
fourth paramete r , she m ust type three com mas t o s i g n ify accepta n c e
of the first t h r e e " d efault" parameters . I f the m ean i n g of t h e above
sentence is not i m m e d iately clear, you have gotten the p o i n t .

When a m e n u offers a set of choices , or the user is otherwise

prompted to respond to a restricted set of options , t h e n the program
should recognize only the responses that are val i d . Do not offer the
user a m e n u of option s , most of which cannot be used. If the user
n eeds to select a file before deciding to E d i t , Save , o r D e lete , let h i m
know. Don't make h i m go down throug h a list, g ettin g t h e same
u n e n li g h te n i n g m essag e , " O ption not currently vali d. "

Enable only those keys you have informed the user you are enabl i n g .
Do not prompt: " P ress E s c A P E to e n d , R E T u R N to contin u e . . . " and fail
to announce that s P A c E bar will e l i m i nate this afternoo n ' s files . The
classic n egative exam ple of this is an early Apple text e d itor with a
verified replace option . Accord i n g to the man ual ( n o i n structions were
d isplayed) , R meant replace this occurre n c e , s P A c E bar s i g n ified d o
not replace this occurrence . The actual code w a s s u c h t h a t any
c haracter with an ASC I I valu e of 82 ( R ) o r above caused a
replacement, and any character with an ASC I I val u e less than 82
caused a ski p . Therefore , " [ " would replace , " 8 " would n o t , " /\ " w o u l d
replace , " , " w o u l d not. Confusion y e t reigns o v e r t h a t o n e .

Having presented t h e rule , here is t h e exception : w h e n u s i n g s P A c E

bar or R E T u R N as a switch ( " Press R E T u R N to conti n u e " ) you may want
to accept all reasonable keys surro u n d i n g the intended target, so as to
not penalize the user for poor aim .

36
Error Messages
E rror messages should alert the user, identify the problem, and direct
the user toward solutions. They should do so with a m i n i m u m of
d isruption : ring the bell once-the whole room does n ' t need to know the
user has yet again made a fool of himself.

Remove the error m essag e as soon as the user takes proper action
to correct the condition . Users will believe you : as long as the
m essage is there , they will conti n u e to correct the probl e m . I t has
been shown that attempting to correct a problem that has already
been corrected will usually result i n a brand new prob l e m .

There are two classes of error m essag es that either i n t i m idate o r

infu riate users .
First, the computer-gibberish special :

Application error # 1 4 63

Error m essages should not only provide i nformation ( i n the user's native
tongue, not computerese) as to what the e rror was, but should offer
solutions as to what the user can do to correct the situation . A better
m essage might be:

You have not yet selected the name of the file you want to work
from . Please type the name of one of the above files .

Second, the it's-easier-to-flag-an-error-than-correct -it erro r :

Data entry error: no comma after Aardvark

Users soon catch on that if the computer/lang uage/program ( everythi n g

gets blamed) knows f o r a fact that there s h o u l d be a com m a afte r
Aardvark, that t h e computer/lang uage/program s h o u l d s u p p l y said
comma. Therefore, the computer/language/program is either really
stupid or is lying .
Your application should have a designated area of the screen where
error m essages are displayed . The usual location has come to be l i n es
23 and 2 4 of the display , but whether you choose these l i n es or not,
make the location consistent. Long help instructions may requ i re a
d ifferent " pag e " . Preserve the contents of display as m u c h as possible
while providing help, and once help is term inated, restore the context
completely.

Please do not ever use the word default i n a program designed for
h umans . Default is something the mortgage went into right before the
evil banker stole the Widow Parson ' s house. There is an exhaustive list
of substitutes ( previous, automatic , standard , etc . ) i n the Appendix to
How to Write a Man ual .

37
 Defaults should be declared, not assumed . U n d eclared ( not d isplayed)
d efaults such as pressing R E T u R N for Yes (or for No?) will cause
confusion and anger.

You need not declare E s c A P E every ti m e you enable i t : E s c A P E always

g ets you out of where you are, to where you came from, without
causi n g damage or confusion . As long as you ad here to that b e n i g n
defin ition, y o u m a y f e e l f r e e t o slip i n E s c A P E anywhere .

Displays

I nverse . There are many recent model home color TVs and older black
and white TV's that display inverse mode very poorly . I nverse mode can
be used effectively to accent screen material, particularly on the l i m ited
40 column screen of the Apple I I and II Plus . It should be used creatively
i n business software where it is expected the user will have a q uality
mon itor. However, for software aimed for the home market, avoi d
i nverse m o d e unless t h e entire screen or several adjacent l i n es are
simultaneously inversed .

Flashing mode should only be used to indicate i m m in e n t destruction of

data or the program .

Focus. TV sets in particular, as well as many lower-priced monito rs,

have very poor focus in the extreme corners . Use the corne rs for fam iliar
character groupings (such as words), rather than clusters of u nrelated
characters (such as numbers) . The h uman mind can figure out that what
looks l i ke " B ASIC F U N CTIONS" is probably " BASIC F U N CTIONS", but
will have less luck discern ing that what looks l i ke " 1 500.00 " is really
' ' 7500 .00 ' ' , an error that could have far-reaching effects . Keep i nput
lines away from the corners for the same reason : the user needs to be
able to check each individual character typed .

Jargon

Avoid computer jargon . A great deal of it has an u nrelated e m otional

charg e . ( Abort, for example . ) The appendix to How to Write a Man ual
has a comprehensive list of standard terms .

38
Keycap Names

Whenever possible . call keys by the names printed on them . written out
i n full . Three of the keys do have a standard abbreviation :

First choice Second choice Abbreviation (last choice)

(gJ OPEN-APPLE OA

lil SOLI D-APPLE SA

(CON T R O L ) CONTROL CTRL

The Apple II and Apple I I Plus have c T R L printed on the c o N T R o L key

and should therefore be prom pted by " c T R L" as a fi rst c h o i c e .
( H owever, the Apple l i e has c o N T R o L spelled out on the c O N T R o L
key . ) Fore i g n - language keyboards have various special symbols for
s h ift, caps lock, tab and retu rn ; use the " local " character in each
" local " version where possi b l e .

Abbreviation s

U s e abbreviations o n l y where absolutely necessary or w h e r e a n

abbreviation is better understood than what it stands for, e . g . 8 P M. .

Programs should begin with a clear announcement of the title of the

program, authorship credits, and a copyright notice (if any) .

The user should not be faced with page after page of i nstructions :
experience has proven that people simply will not read the m . Rathe r,
supply help as it is needed . One way of doing that is described in the
section on menus .

When you try your program out on new users, be sensitive to the times
they need fundamental help in using the features of the program s . For
exam ple, while you may have a program portion with d etailed
explanations on why ellipsoid analysis is so effective i n figuring hog belly
futures . your user may never get there : you may not have provided
necessary help in how to enter preliminary data.

The standard help key on the Apple l i e and Apple Ill series computers is
either O P E N - A P P L E - ? or S O L I D - A P P L E - ? (The S H I F T should not b e

39
 r e q u i red : therefore, also accept o P E N - A P P L E - I and s o L r o
A P P L E -/. )

The stan dard h e l p key on the Apple I I and Apple I I P l u s, w h e r e

practical, is a q uestion m a r k or slash, or else E s c A P E ? o r E s c A P E I .

The normal location f o r h e l p m essag es is the bottom of the scre e n .

Whether you use this location or anothe r, make your location
consistent. When using a separate help screen, clearly title it as a
" h e l p " display, and make the transitions as smooth as possi b l e . W h e n
h e l p has b e e n g iven, restore t h e screen t o its original conditio n .

Many of the menu g u idelines may appear somewhat arbitrary-they are .

It appears only happy coincidence that so many developers are maki n g
m e n u s s o similar. A s with many aspects o f h uman inte rface standards,
what is i m portant is that one standard be set so the poor user can get
used to one way of doing things. It is not n early so i m po rtan t what that
standard is.

A menu should display all choices legibly, using n u m bers for menu
selection . Research has shown that people will learn a n u m be r on an
often used menu as quickly as a letter, even though letters on the
surface appear more friendly. ( " Was that E for Edit or E for E rase?" )
M nemonic letter schemes are a nig htmare t o translate, a n d well over half
of computer users are not touch-typists . For these reason s and others,
the vast majority of developers have settled on n u m be rs .

If you d o settle o n letters, for your own reasons, b e sure to b e

consistent: don't make the user use n u m bers for o n e section o f a
program and letters for anothe r .

A l l sub-menus should allow t h e u s e r t o move t o the n ext h i g h e r m e n u by

pressing the E s c A P E key . The main m e n u s h o u l d not have an E s c A P E
key option, so that the user can feel confi d e n t about lean i n g o n the
E s c A P E key to get all the way back to the top level, without worry i n g
about being bounced completely o u t of the prog ram u p o n reac h i n g the
top leve l . Each m e n u should (redun dantly) have a last option that w i l l
m o v e the user back t o the n ext h i g h est leve l . The Main M e n u ' s option
should e n d the prog ram .

40
The following is an exam ple of a m e n u using the stan dard m e n u format :

Commodity Analyzer Futu res Men u Select Future

1 . Pork Belly Futures

2 . Corn Futures

3 . Present Futures

4. Crystal Ball Futures

5 . Return to the Main Menu

Type your Selection (1 -5) and press RETU RN : _ . .

Options: E S C A P E to leave 0 P E N - A P P L E - ? for help

The exact n u m ber of lines devoted to the three regions is not g raven i n
sto n e : t h e real standard being striven for is that there be three regions
with solid lines separating them, that these be devoted to titles, choices
presented, and instructions. (The Apple I I and Apple I I Plus can not
produce a solid line in text mode ; use either their hyphens o r their short
underline characters.

The title region can have up to three titles ( usually two i n forty-col u m n
mode) . T h e middle title ( o r lett title, if o n l y 2 ) should be t h e n a m e of the
menu, and it should contain the word, " m e n u . " Other displays you will
use, such as data entry and information, may have a s i m i lar format: make
sure your user is clearly aware of what he is being asked to d o . S i m ilarly,
on information screens, do not n u m be r itemized lists, asterisk them :
otherwise, about 25% of your users will try to type i n a "selection " .

You may use o r not use the other titles as you see fit, but they should
have a consistent meaning throug hout a given application .

Note that a field length longer than one has been allowed for the n u m ber
input. A field length of only one character will not give the user enough
feedback as to how the in put works . Users who have typed the wrong
n u m ber will often panic, assuming the computer has somehow locked
up. By giving them a few extra spaces, they can see from the action on
the screen what is going on and deduce what to do about it. Since you
will be stripping leading and trailing spaces ( wo n ' t you?), this extra
freedom afforded the user will not affect the program .

The instruction region doubles as the error m essage region .

41
One method you can use to enable the user to get descriptions of any
option is to have them type the n u m be r of the option , followed by the
help key ( o P E N - A P P L E - ? on the Apple lie and Apple 1// , ? o n the
Apple I I and I I Plus). The user is able to get extensive i nformation o n ly
on those items of interest, without havin g to wade thro u g h masses of
i n formation that are not needed.

Routines for doing these m e n us will be available from A p p l e : first i n

Pascal for t h e Apple Ill i n t h e Screen Manager a n d i n B AS I C f o r t h e
Apple I I series within t h e sam ple programs ( M ag i c M e n u , D i s k M e n u ,
etc . ) supplied with t h e Apple l i e Applesoft Tutorial a n d Reference
manuals package . The BAS I C version is i m p l e mented with the h e l p
faci lity described above .

(The following is a repeat of an earlier section . The keyword display is

repeated here to make the document useful for refere n ce . )

I n order to type a command o r list selection without prompti n g , the user

must)earn what words he can type at any one point i n the p rogram . This
learning problem can be overcom e i n a q uite straightforward man n e r by
displaying a list of all options then availab l e . Typically, this can be done
by creating a display similar to the standard m e n u format , with the center
region devoted to the list of words:

Commodity Analyzer Belly P rocesses Pork B e l l i e s

Commands : Inventory Types :

display complete bellies

graph partial bellies

compute dancing bellies

buy

sell

eat

delete

Type your instruction and press RETU R N : _

Options: E S C A P E to leave O P E N - A P P L E - ? for help

As the available options change, so do the options displaye d . Thus, the
user knows at every point exactly what she can select. (The display of
command words could be made optional through the novice/expert flag ;
variable lists of words, such as file names, should always be visible . )

Informed When Are

When the computer will be either carrying out computations o r
accessing t h e d i s k f o r a n extended period of time, a m essage s h o u l d be
left on the screen, instructing the user that the computer will return
shortly (this is not the suggested m essage). Some periodic chan g e in
the screen, as a lengthening line of periods (hence periodic) should
occur so the user knows the computer has not s i mply gone into an
endless loop somewhere . When the computation period is over, clearly
sig nal it: simply showing up with a blinking cursor over i n the corne r
won 't d o after a brief, 20 -minute pause .

43
 -------- --

20525 M ar i a n i Avenue
Cu pert i no, C al i forn i a 95014
(408) 996-1 01 0
TLX 1 7 1 - 576
1 982 Apple Com puter Inc . A2F21 1 6 1 1 /82 030-062 1 A