User Documentation Documentation Guidelines Break the documentation down
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
- Slides: 17