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

Task Orientation Approach Who performs each task? What action begins each task? What are the specific steps involved in performing the task? What action ends each task?

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

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

Color Print and Background Black on white is best Other possibilities are: –Green on white –Blue on yellow –Black on yellow –Red on yellow

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