1. 1 Software User Documentation Don Bagert CSSE 375, Rose-Hulman October 9, 2006

2. 2 Reference  Slides 4-11 are mostly taken from the following University of Michigan-Dearborn page: http://www.engin.umd.umich.edu/CIS/course.des/cis577/lecture/Lec12.html  Course Instructor: Bruce Maxim

3. 3 Outline  Likely User Audience  Printed Documentation Types  Online Documentation  Problems in Software Documentation  Why is reading from a computer display more difficult than reading from paper?  Printed Manual – Suggested Guidelines  Process of Developing Printed Manuals  User Documentation Life Cycle

4. 4 Likely User Audience  Users  Operators

5. 5 Printed Documentation Types  Alphabetic command lists  Quick reference cards  Brief getting started notes  Novice user tutorials  Detailed reference manuals

6. 6 Online Documentation  Help facility  Tutorials  Demos  Man pages (Unix)

7. 7 Problems - software documentation often:  Merely presents operator descriptions  Is organized according to system functions, not user goals  Is too voluminous for novice users  Talks about how the system works and not how it can be used

8. 8 Why is reading a from computer display more difficult than reading from paper?  Poor fonts  Low contrast between characters and backgrounds  Emitted light rather than reflected  Small displays require frequent page turning  Layout and formatting problems  Reduced body motion make them more fatiguing  Displays less familiar than book

9. 9 Printed Manual – Suggested Guidelines  Let users 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

10. 10 Process of Developing Printed 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

11. 11 User Documentation Life Cycle  Develop specifications  Prototype  Draft  Edit  Review  Field test  Publish  Perform post project review  Maintain