CS 552, Spring 1998
Guidelines for Online Documentation and Error Messages
From J. Dumas, 1988, Designing User Interfaces for Software,
- Write online documentation in plain English.
- Address the user directly as "you", and use the active voice.
For example, "Three reports can be printed by the users of this program"
is more direct as: "You can print three reports with this program."
- Use simple action verbs to describe procedures; don't use nouns
to replace pronouns, verbs, and adjectives. For example, instead
of "Modification", "Maintenance", and "Selection", use
"Modify" or "Change", "Keep", and "Select" or "Choose."
- Describe procedures in logical order. Rather than
"Press the Enter key, but before you do, be sure that you have saved
your file or you may lose it," say
"Be sure to save your file before you press the Enter key."
- Use simple English words, not computer or other jargon.
Avoid terms that are unique to the computer profession (such as
"filespec" or "abend"). Avoid terms that have meaning outside
computing but a special meaning within it (e.g., "abort", "utility").
Also, avoid terms that are made up in order to describe some special
function (e.g., "ungroup", "de-archive").
- Avoid humor in online documentation.
- Use status messages to tell the user what the software is
doing, where the user is in a sequence, and what
options the user has selected or that are available.
- Be as specific as possible in describing the cause of an
error. Do not use error codes.
Whenever possible the error message should indicate what corrective
action the user should take.
Don't assign blame to the user or the software in an error message;
instead, use a neutral tone.
Consider describing error messages at more than one level of detail
(e.g., for new versus advanced users).
- Be consistent in the format, wording, and placement of
messages. Write short sentences and short paragraphs.
Use bullets, numbered lists, and tables to make it easier to find the
most important information - and leave ample blank space.
Use examples to show users what they should type and what the results
will look like.
- Do not expect the user to read more than about three screens
of help at one time.
Taken from J. R. Brown and S. Cunningham, 1989, Programming the
User Interface, John Wiley & Sons.
- Tell the user as specifically as you can what the error or
- Tell the user as specifically as you can what might fix the
- Do both of the above in simple language with clear action
verbs that emphasize the user's control of the program.
Adapted from W. O. Galitz, 1996, The Essential Guide to User Interface
Design, John Wiley & Sons.
Examples of poor error messages:
- ERROR OPENING FILE
- PROTECTION VIOLATION #367
- Miscellaneous permanent error
- FATAL I/O ERROR
- EOF found after record 139
- CHECKSUM ERROR
- Wrong code, try again
- You entered and invalid month
Characteristics of poor error messages:
- Vague and/or contain meaningless codes
- Blame the user
- Have a negative tone
- Attempt humor, but are insulting
- Don't help solve the problem
- Use all upper-case letters, reducing readability
Examples of error message improvements.
ERROR 56 OPENING FILE
|The filename you typed cannot be found. Press F2
to list valid names.
JOB ABORTED! FILENAME ILLEGAL.
|Retype filename (for example, REPORT.DOC).
|Type an option from the menu
THE LOCK MANAGER CANNOT PROCESS YOUR REQUEST NOW.
PLEASE RETYPE YOUR REQUEST AFTER 6 PM.
|Print requests of more than 500 pages cannot be run
before 6 PM. Reenter your request at that time.
RETYPE THE NODE NAME AS SPECIFIED IN THE NETWORK MAP.
|Retype the node name as either SI01 or SI02.
|File REPORT.DOC, is locked. Before
requesting the file again, type the command: UNLOCK