User Documentation Documentation Guidelines o Break the documentation

User Documentation

Documentation Guidelines o Break the documentation down by tasks o Plan for an audience o State the purpose of the document o Organize the documentation o Develop a product visualization o Pick the appropriate medium o Decide on a page format and layout o Design for ease of editing

Break Down by Task o Users don’t like to read documentation o Avoid software orientation o Avoid menu orientation o Avoid user-role orientation (e. g. , Operators Guide, Programmers Guide, etc. ) o Use Task Orientation

Task Orientation o Who performs each task? o What action begins each task? o What are the specific steps involved in performing the task? o What action ends each task? o Are there any variations in H/W or in the general environment which would alter it?

Plan for an Audience o Distinguish between audiences n Relative computer sophistication n General background, training, and education n Attitude toward information o Types of audiences n Novice n Intermediate n Expert n Casual

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

Organize Text o Text should be organized in ways expected by readers o The organization should be apparent to readers o Let the reader know the organization with explicit words or pictures

Organizational Alternatives o Chronological order o Most important to least important order o Order of need o Order of difficulty o Question/answer order o Comparison/contrast order o Spatial order (with respect to the screen) o Alphabetical order

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

Pick the Appropriate Media o Manuals o Brochures o Reference cards o Online documentation

Reference Card Attributes o Contain only most relevant information o Have adequate use of white space o Are legible o Have effective headings o Provide easy access to information o Provide logical groupings of information

Online Documentation Considerations o User cannot cope with as much information online as in written form o Users have less success finding information online than similarly trained people using printed sources

Determine Page Format and Layout o Give attention to: n n n Legibility of print Spatial arrangements Color print and background

Legibility of Print o Typefaces n Helvetica or Letter Gothic are preferred n Serif is better than sans serif n Courier photocopies better o Readers like use of boldface text o Users prefer Arabic over Roman o Italicized text is harder to read o Mixed typefaces slows reading

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

Color Print and Background o Black on white is best o Other possibilities are: n Green on white n Blue on yellow n Black on yellow n Red on yellow o 5 ½ x 9 layout is becoming standard (less foreboding, easier to handle, difficult to photocopy)

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

What Makes Good On-Line Documentation? o Well Presented – fonts, colors, etc. o Well Organized – take into account that only one screen can be seen o Well Written – grammar, spelling, etc. o Balanced – with respect to text and graphics o Up To Date – information should be regularly updated

What Makes Good On-Line Documentation? (cont’d) o Interesting – tone and style are friendly and informal o Well Structured – homepage needs to give an overall plan for the site and structure should not be cumbersome o Searchable – contain common key words to make finding easy o Consistent – there must be consistency in style among the pages

What Makes Good On-Line Documentation? (cont’d) o Impressive – at least the homepage should have high visual impact o Entertaining – users have a short attention span, and like to have fun o Maintained – changes must be made in a timely manner o Reliable – must be accurate and hyperlinks must be current