User Documentation

1. User Documentation

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

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

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

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

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

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

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

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

10. Pick the Appropriate Media • Manuals • Brochures • Reference cards • Online documentation

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

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

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

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

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

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

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

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

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

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