User Documentation

Documentation Guidelines  Break the documentation down by tasks  Plan for an audience  State the purpose of the document  Organize the documentation  Develop a product visualization  Pick the appropriate medium  Decide on a page format and layout  Design for ease of editing

Break Down by Task  Users don’t like to read documentation  Avoid software orientation  Avoid menu orientation  Avoid user-role orientation (e.g., Operators Guide, Programmers Guide, etc.)  Use Task Orientation

Task Orientation  Who performs each task?  What action begins each task?  What are the specific steps involved in performing the task?  What action ends each task?  Are there any variations in H/W or in the general environment which would alter it?

Plan for an Audience  Distinguish between audiences Relative computer sophistication General background, training, and education Attitude toward information  Types of audiences Novice Intermediate Expert Casual

Purpose of Document  What is the specific technical problem?  What is the general business background problem it also needs to answer?

Organize Text  Text should be organized in ways expected by readers  The organization should be apparent to readers  Let the reader know the organization with explicit words or pictures

Organizational Alternatives  Chronological order  Most important to least important order  Order of need  Order of difficulty  Question/answer order  Comparison/contrast order  Spatial order (with respect to the screen)  Alphabetical order

Develop a Product Visualization  Create a picture in the reader’s mind of the system.

Pick the Appropriate Media  Manuals  Brochures  Reference cards  Online documentation

Reference Card Attributes  Contain only most relevant information  Have adequate use of white space  Are legible  Have effective headings  Provide easy access to information  Provide logical groupings of information

Online Documentation Considerations  User cannot cope with as much information online as in written form  Users have less success finding information online than similarly trained people using printed sources

Determine Page Format and Layout  Give attention to: Legibility of print Spatial arrangements Color print and background

Legibility of Print  Typefaces Helvetica or Letter Gothic are preferred Serif is better than sans serif Courier photocopies better  Readers like use of boldface text  Users prefer Arabic over Roman  Italicized text is harder to read  Mixed typefaces slows reading

Spatial Arrangements  Use 40% print density and wide margins  Use active white space  Ragged right margins are preferred

Color Print and Background  Black on white is best  Other possibilities are: Green on white Blue on yellow Black on yellow Red on yellow  5 ½ x 9 layout is becoming standard (less foreboding, easier to handle, difficult to photocopy)

Plan for Updating  Number and title all pages  Number sections separately  Place change page sheet at front  Include reader comment endsheet

What Makes Good On-Line Documentation?  Well Presented – fonts, colors, etc.  Well Organized – take into account that only one screen can be seen  Well Written – grammar, spelling, etc.  Balanced – with respect to text and graphics  Up To Date – information should be regularly updated

What Makes Good On-Line Documentation? (cont’d)  Interesting – tone and style are friendly and informal  Well Structured – homepage needs to give an overall plan for the site and structure should not be cumbersome  Searchable – contain common key words to make finding easy  Consistent – there must be consistency in style among the pages

What Makes Good On-Line Documentation? (cont’d)  Impressive – at least the homepage should have high visual impact  Entertaining – users have a short attention span, and like to have fun  Maintained – changes must be made in a timely manner  Reliable – must be accurate and hyperlinks must be current