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
- Slides: 20