From J. Dumas, 1988, Designing User Interfaces for Software, Prentice-Hall.

1. Write online documentation in plain English.

2. 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."

3. 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."

4. 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."

5. 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").

6. Avoid humor in online documentation.

7. 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.

8. 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).

9. 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.

10. 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.

1. Tell the user as specifically as you can what the error or problem is.

2. Tell the user as specifically as you can what might fix the problem.

3. 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.

   Original Message	Improved Message
   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).
   WRONG CHOICE.	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.
   LOCKED FILE.	File REPORT.DOC, is locked. Before requesting the file again, type the command: UNLOCK REPORT.DOC.