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

2 Reference  Slides 4-11 are mostly taken from the following University of Michigan-Dearborn page:  Course Instructor: Bruce Maxim

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 Likely User Audience  Users  Operators

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

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

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 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 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 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 User Documentation Life Cycle  Develop specifications  Prototype  Draft  Edit  Review  Field test  Publish  Perform post project review  Maintain