User Documentation

1. User Documentation CIS 375 Bruce R. Maxim UM-Dearborn

2. System Delivery • Training • Documentation • Likely User Audience • Users • Operators

3. Printed Documentation • Alphabetic command lists • Quick reference cards • Brief getting started notes • Novice user tutorials • Conversion manuals • Detailed reference manuals

4. On-Line Documentation • Man pages • Help facility • Tutorials • Demonstration

5. Common Documentation Problems • Simply presents operator descriptions • Organized according to system functions, not user goals • Too much for novice users to take in • Rarely presents complete methods explicitly • Talks about how system works, not how it can be used • User must problem solve even simple tasks • Rarely presents selection rules

6. Printed Manual Guidelines • Let user's task guide organization • Let user learning process shape sequencing • Present semantics before syntax • Keep writing style clean and simple • Show numerous examples • Offer meaningful and complete sample sessions • Draw transition diagrams • Use advance organizers and summaries • Provide table of contents, indices, and glossaries • Include list of error messages • Give credit to all project participants

7. Process for Developing Print Manuals • Use professional writers and copy editors • Prepare user manuals before implementation • Review drafts thoroughly • Field test early drafts • Provide feedback mechanism to readers • Revise to reflect changes regularly

8. On-Line Manuals • Can provide successively more detailed error explanations • Personalized instruction on system use is possible • Examples of correct commands • Descriptions of current system parameters • Lists of commands • News for system users • List of available user aids

9. Advantages of On-Line Manuals • Information is available when computer is available • User don’t need space to open printed manuals • Manual updates are low cost • Electronic indexing allow fast search of manual • Multimedia help may be beneficial

10. Disadvantages of On-Line Manuals • Displays may not be as easy to read as print manuals • Each screen contains less info than 1 printed page • Interface operations may confuse novices • Splitting display among work, help, and tutorials leaves less useful screen space • Additional burden on user

11. Why is it harder to read text on computer screens? • Poor fonts • Low contrast between characters and backgrounds • Emitted light rather than reflected • Small displays require frequent page turning • Display placement too high • Layout and formatting problems • Reduced body motion make them more fatiguing • Displays are less familiar than books