User Manuals: What Does the User Really Need?
Roy L. Chafin
Jet Propulsion Laboratory
C a l i f o r n i a I n s t i t u t e of Technology
Introduction
The purpose of the user manual is to assist the
user in effectively operating a system. T h i s ob-
jective is complicated by the wide diversity of
user s k i l l s , and user tasks. The quality of a user
manual is affected not only by the level of effort
exerted by the system developer in writing the
manual, but also by the degree of matching between
the user manual and the user's needs. The documen-
tation writer must supply both e f f o r t and direction
in writing the user manual. T h i s paper addresses
the direction issue. The question is: What does
the user really need?
This issue was brought out in a man-computer inter-
face research project at the Jet Propulsion Lab
oratory, a NASAf a c i l i t y . As a part of this pro-
ject, the Deep Space Network tracking station op-
erators were interviewed in a series of focus
groups (1). Approximately 100 operators participa-
ted in groups of two to six. In analyzing the
focus group data, three things were observed. First,
the central position of the software documentation
(user manual) in the the operation of the station.
The knowledge required to run the station was
greater than the operator could keep in his i n t e r -
nal knowledge; he needed the user manual. Second,
the operators were very unhappy with current user
manuals. However, they had d i f f i c u l t y identifying
the cause of t h e i r unhappiness. Third, the oper-
ator's complaints were contradictory. Some com-
plained that the descriptive material was inad-
equate, i t was too cryptive and didn't explain the
system. Others complained that there was extra-
neous material in the manual and they couldn't
find anything when they needed i t .
In developing an overview of the focus group data,
i t became clear that three different documents
were required:
(1) A task-oriented set of procedures which
gave the operator specific instructions to solve
the daily tasks confronting him.
The research on which this paper was based was
performed by the Jet Propulsion Laboratory,
California Institute of Technology, under
contract with the National Aeronautics and Space
Administration.
36
(2) A reference document to allow the operator
to rapidly look up specific items. Actually, this
category consisted of two documents, a general
reference document, and a quick-look reference doc-
ument.
(3) A Theory of Operations document was requir-
ed for the operator to develop his understanding
of the system.
I t became clear that different operators had d i f -
ferent documentation needs, and even the same op-
erator had different documentation needs at d i f f e r -
ent times. The intent of this paper is to identify
the user and task variables which affect the user's
documentation needs and present models which can
be used in understanding the process and in writing
user documentation.
User Diversity.
We w i l l consider a user s k i l l model and w i l l relate
documentation requirements to that model. Although
the range of user s k i l l levels is continuous, i t
is convenient to divide the range into four parts
(2). Users can be considered to be naive, novice,
competent, or expert.
Naive users have l i t t l e or no
understanding of the system, what
i t does, nor how to operate i t .
Novice users have some knowledge
of the system's objective, but do
not know how to operate i t .
Competent users understand the
system and how to use i t .
Expert users understand the system
so well that they operate i t
automatically, without having to
think about i t .
We would expect that each of these s k i l l levels
would have different documentation needs. Shnei-
derman's syntactic/semantic model (3) provides a
good tool to characterize the various user s k i l l
levels. The syntactic/semantic model suggests that
that there are two levels of a c t i v i t y required to
accomplish a task. There are general concepts,
 important to the task at hand, called semantic
knowledge; and a more precise detailed Enowledge
of the particular a c t i v i t y called syntactic know-
ledge. In terms of user's knowledge, semantic
]~-n'GwTedge is the basic understanding of what the
program or system does and how i t does i t .
tactic knowledge is knowledge of the specific com-
mand functions, messages, and system outputs. This
syntactic/semantic model can be extended by con-
sidering contextual knowledge, that is, the know-
ledge of where the system f i t s in context of the
user's task.
We can now consider the user's documentation needs
in terms of the s k i l l level model and the extended
syntactic/semantic model.
The naive user requires everything. He needs to
understand the context in which the system is
used, as well as what the system does (semantics)
and how to make the system work (syntactics). For
the contextual knowledge, he needs a document that
describes the system scope, not just the scope of
the document, but where the system f i t s into the
overall tasks. I t should also explain the equip-
ment configuration required to use the system. A
Theory of Operations section is needed to provide
the semantic knowledge. An Operating Instructions
section is needed to provide the syntactic know-
ledge. This is the detailed instructions on how
to operate the system. Extensive examples in the
operating instructions are essential. I t must be
understood that a naive user places the greatest
demand upon the user documentation. And the docu-
mentation is most c r i t i c a l to the successful oper-
ation of the system by a naive user.
Contextual
Knowledge
Scope
Naive Required
Novice Not required
Competent Not required
Expert Not required
Manual Sections and User Skill levels
Another concept that is important is cost/benefit
ratio. A u s e r approaches documentation with a
mental evaluation (usually very subjective) of the
cost of using the documentation against the bene-
f i t s of using i t . I f the cost is perceived to be
high because the book is thick, i t has excessive
material, i t is poorly written, or i t is poorly
organized, he perceives that i t w i l l require a
great amount of effort and he w i l l not use the
documentation. I f no other source of knowledge
is available, he w i l l most l i k e l y decide that he
can't handle the system and w i l l not use i t . This
is the source of many unsuccessful systems. When
naive users are expected, the developers should
plan on placing extra effort on the user docu-
Syn- mentation.
The novice user has pretty good contextual know-
ledge. He most l i k e l y w i l l need semantic know-
ledge refreshing occasionally. But his greatest
requirement for u s e r documentation is syntactic
knowledge. He needs to know how to make the system
work. When novice users are expected, the Scope
and Theory of Operations sections are needed but
to a lesser extent. The principal novice user's
need is the Operating Instructions, and special
attention should be placed on this section. The
Operating Instructions should be extensive and com-
plete; however, examples are of lesser importance
because the user has a better understanding of the
system.
The competent user w i l l not need as much support
from the documentationas the previous s k i l l levels.
He occasionally w i l l need to refresh his syntactic
knowledge. He w i l l most l i k e l y use a quick-look
short form reference for commands, system messages,
and outputs. This quick-look reference w i l l be most
effective when i t is just a l i s t of the commands
contained on one page.
The expert user almost by d e f i n i t i o n needs l i t t l e
or no documentation. His system knowledge is so
great that he can operate the system automatically,
that is, he doesn't have to think about what he is
doing.
Figure 1 summarizes the type of knowledge needed
at the various user s k i l l levels.
Semantic Syntactic
Knowledge Knowledge
Theory of Operating Quick look
Operation Instructions
Required Required Probably w i l l
not be used
Reference Required May be Useful
Not required Reference Required
Not required Not required Reference
Figure 1
The documentation should be designed to f i t the
user s k i l l level, assuming that the user popula-
tion is f a i r l y homogeneous and is stable. Docu-
mentation f i t t e d to the user s k i l l level is most
effective because i t is the minimum required to
supply the user's needs. Excessive documentation,
i . e . , beyond what a u s e r r e a l l y needs, requires
an excessive cost in terms of effort required to
use i t , (cost/benefit ratio) and so becomes less
effective.
37
Range o f Users
T y p i c a l l y , the range of user s k i l l levels pre-
cludes t a i l o r i n g the documentation to a s i n g l e
skill level. And, very o f t e n an i n d i v i d u a l user
w i l l range through the s k i l l l e v e l s during h i s
c a r e e r . He w i l l s t a r t as e i t h e r a naive or novice
user and progress towards e x p e r t , stopping at some
p o i n t along the way. So, the user p o p u l a t i o n
w i l l o f t e n contain a non-homogeneous mix of user
s k i l l l e v e l s which change as they become more
experienced, and t u r n o v e r b r i n g s in new users.
Also, f o r l a r g e systems, an i n d i v i d u a l may be an
expert in the part of the system which he exercises
o f t e n and y e t be a novice in the p a r t s o f the
system which he uses i n f r e q u e n t l y .
A non-homogeneous user p o p u l a t i o n would suggest a
documentation l e v e l to match the needs o f the
lowest s k i l l level. S o m e aspects of excessive
user costs ( c o s t / b e n e f i t r a t i o ) f o r excessive doc-
umentation can be a m e l i o r a t e d by d i v i d i n g the doc-
ument i n t o more a p p r o p r i a t e p a r t s which are pub-
l i s h e d s e p a r a t e l y , or at l e a s t as separate volumes,
each optimized f o r i t s r o l e in supporting the
d i f f e r e n t user s k i l l l e v e l s . Thus, a user r e f e r s
only to the document which he needs, and because
he d o e s n ' t have to contend w i t h excessive document
s i z e , his e f f o r t costs are l e s s .
Other Influences on Documentation
There are o t h e r t h i n g s to c o n s i d e r when d e c i d i n q
on the l e v e l of documentation t o provide f o r a
system. A good t r a i n i n g program w i l l r a p i d l y r a i s e
the user s k i l l l e v e l and thus reduce the demands
on the documentation. P a r t i c u l a r l y , the Theory o f
Operations s e c t i o n can be reduced. I t cannot be
e l i m i n a t e d because i t would s t i l l be needed f o r
r e f e r e n c e . Another phenomena which would reduce
the need f o r e x t e n s i v e documentation is the a v a i l -
ability for a "local expert". Very o f t e n in an
i n s t a l l a t i o n , one i n d i v i d u a l w i l l develop his know-
ledge to the p o i n t where he i s an expert on the
system. Other users w i l l go to him f o r h e l p .
When a l o c a l expert i s a v a i l a b l e , i n d i v i d u a l users
w i l l u s u a l l y p r e f e r his help over t h e i r own use of
the documentation. The l o c a l e x p e r t can r a p i d l y
determine t h e i r s p e c i f i c problem, f i l t e r out e x t r a -
neous d a t a , and g i v e them the i n f o r m a t i o n t h a t
a p p l i e s to t h e i r problem. This process costs the
user much less time and e f f o r t than using the
documentation. I f i t can be assumed t h a t a l o c a l
expert w i l l be a v a i l a b l e , the developers can reduce
the level of both the Theory of Operations and
the Operating I n s t r u c t i o n s . Again, these sections
s h o u l d n ' t be e l i m i n a t e d because they may be needed
for reference.
An interesting aspect of the system design that
affects the user's need for documentation is the
robustness of the system. When the user has b u i l t
up confidence that the system w i l l not break when
he does something wrong, he w i l l often be tempted
to go ahead and t r y things rather than looking
them up in the manual. I f human factors have been
incorporated in the system desiqn ( i . e . , the system
is easy to use) and i t is impervious to operator
error, the documentation level can be reduced.
32
Terminology
I t i s common t o suggest t h a t documentation should
be w e l l w r i t t e n . The concept of w e l l w r i t t e n i s
d e s i r a b l e but hard to d e f i n e . G o o d English i s
e s s e n t i a l because t h a t i s the common denomination
in communications. S t y l e is a l s o i m p o r t a n t . Prob-
ably the best suggestion on s t y l e i s t h a t i t should
be c o n s i s t e n t w i t h s t y l e o f o t h e r documentation
used by the user. A very i m p o r t a n t issue i s the
t e r m i n o l o g y used in the documentation. The t e r m -
i n o l o g y should come from the u s e r ' s p e r c e p t i o n o f
the system r a t h e r than the programmer's. The u s e r ' s
view of a system i s from the o u t s i d e . He under-
stands the system in terms o f the i n t e r a c t i o n o f
the basic f u n c t i o n s of the system. The programmer
views the system from the i n s i d e because he i s
so f a m i l i a r w i t h the system d e s i g n . I t i s encum-
bent upon the w r i t e r t o express the f u n c t i o n a l
a c t i v i t y o f the system in terms o f an o u t s i d e
view. When the programmer i s a l s o the w r i t e r ,
proper p e r s p e c t i v e becomes d i f f i c u l t . This lends
support to the p o l i c y of using t e c h n i c a l w r i t e r s
f o r user documentation r a t h e r than r e q u i r i n g the
programmer to w r i t e i t .
Task D i v e r s i t y
Task oriented variables also affect the level and
direction of required documentation. A system may
be embedded within a task such that oPerating the
system is synonomous with performing the task. A
system dedicated to a single task such as an ac-
counts receivable package or the embedded computer
systems in the DSN tracking stations may be coupled
very t i g h t l y to t h e i r applications. Other systems
may be thought more appropriately as t o o l s , tools
which are used to accomplish many d i f f e r e n t tasks,
or parts of tasks, for example computer aided
design programs or s t a t i s t i c a l packages.
When a system design i s decoupled from the a p p l i -
c a t i o n o r i t i s being used as a t o o l , the user
documentation i s u s u a l l y w r i t t e n in terms o f de-
s c r i p t i o n s o f the c a p a b i l i t i e s of the system and
how those c a p a b i l i t i e s are obtained (Theory of
Operations and Operating I n s t r u c t i o n s ) . I t is up
to the user to determine how those c a p a b i l i t i e s
w i l l be a p p l i e d to his p a r t i c u l a r problem.
Systems t i g h t l y coupled to a p p l i c a t i o n s or embed-
ded systems have two o p t i o n s in the p h i l o s o p h y of
the documentation, The documentation can also be
presented in terms o f the systems c a p a b i l i t i e s
or in terms of the actual a p p l i c a t i o n . Of course,
the most e f f e c t i v e method i s to express the user
manual in terms of the u s e r ' s a c t i v i t i e s , Unfor-
t u n a t e l y , the developer o f t e n i s not knowledgeable
of the actual u s e r ' s environment, so he tends t o
w r i t e the u s e r ' s manual in terms of t h e system
capabilities. When t h i s happens i t i s encumbent
upon the user o r g a n i z a t i o n t o w r i t e Operating Pro-
cedures which d e s c r i b e how the system i s used to
accomplish s p e c i f i c t a s k s . The actual requirement
f o r the task o r i e n t e d procedures depends upon the
s k i l l l e v e l of the user and the c o m p l e x i t y of the
tools.
Summary

The main points of this discussion are:

*Users are different and have different

documentation needs.

*Documentation can be excessive.

Too large or poorly written documents
require too much effort to read, and
they probably w i l l not be used.

*Documentation is more useful when

presented with user's terminology
rather than with programmer's terminology.

A user s k i l l level model has been presented which

can be used to relate u s e r documentation level
to user needs.

Bibliograph~

i. Chafin, R. L.
DSN Human Factors Project Focus Group Report.
Contract No. 955013. Task Order No. RD-142.
Jet Propulsion Laboratory.
California Institute of Technology

2. Chafin, R. L.
"A Model for the Control Mode Man-Computer
Interface Dialogue. 17th Annual Conference on
Manual Control, UCLA Los Angeles, California.
January 16-18, 1981.

3. Shneiderman,B.
Software Psychology Human Factors in Computer
and Information System.
W-WTnthrop Publishers, Inc. Cambridge, Mass.
1980.

39