Documentation and Online Tutorials
System Delivery
Likely User Audience
Printed Documentation Types
- Alphabetic command lists
- Quick reference cards
- Brief getting started notes
- Novice user tutorials
- Conversion manuals
- Detailed reference manuals
Online Documentation
- Man pages
- Help facility
- Tutorials
- Demonstration
Problems with Most Computer Documentation
- Simply present operator descriptions
- Organized according to system functions, not user goals
- Too voluminous for novice users
- Rarely presents complete methods explicitly
- Talks about how system works, not how it can be used
- User must problem solve even simple tasks
- Rarely presents selection rules
Why is reading from computer displays 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
- Display placement too high
- Layout and formatting problems
- Reduced body motion make them more fatiguing
- Displays less familiar than books
Printed Manual Guidelines
- Let user's 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
- Give credit to all project participants
Process of Developing Print 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
User Documentation Life Cycle
- Develop specifications
- Prototype
- Draft
- Edit
- Review
- Field test
- Publish
- Perform post project review
- Maintain
GOMS models provide good starting points for writing documentation.
Guidelines for Using Goals to Organize Task Oriented Documentation
- Use high level goals as a table of contents
- List high level goals in natural task sequence
- High-frequency goals and critical sub goals should be documented fully
- Each user goal should have a complete and executable method
- Judgement calls must be used regarding prior user knowledge of methods and operators
- Methods should be checked for correctness
Limitations of GOMS for Documentation
- Only specifies content and organization of procedural knowledge
- Does not address readability, pedagogy, layout, typography, content, graphics use, etc.
Advantages of Online Manuals
- Information is available when computer is available
- User don’t need space to open printed manuals
- Manual updates are low cost
- Electronic indexing allow fast search of manual
- Multimedia help may be beneficial
Disadvantages of Online Manuals
- Displays may not be as easy to read as print manuals
- Each screen contains less info than 1 printed page
- Interface operations may confuse novices
- Splitting display among work, help, and tutorials leaves less useful screen space
- Additional burden on user
Online Facilities
- Successively more detailed error explanations
- Instruction on system use
- Examples of correct commands
- Descriptions of current system parameters
- Lists of commands
- News for system users
- List of available user aids
Guidelines for Preparing Online Help (Kearsley)
- Make help system easy to access and return from
- Make help as specific as possible
- Collect user data to determine what help is needed
- Give users control over the level of help provided
- Supply different types of help for different types of users
- Make help message complete and accurate
- Do not use help to compensate for poor user interface design
Online Implementation
- Word processing documents
- Hypertext
- Unix man pages
- Help menu
- Key words to organize menu driven help
- Context sensitive help
- Balloon help
Tutorials (Steinberg)
Guidelines for Developing Lessons
- Initial planning - lesson level
- Ripple plans - unit level
- Complete the lesson - lesson level
Writing the Presentation
- Generate unit goals
- Choose teaching technique based on cognitive goal for lesson (recall, comprehension, application, analysis, synthesis, evaluation)
- Write script
- Generate questions and exercises
Checking Lesson for Effectiveness
- Pretest and posttest
- Questionnaires
- Student interviews
- Field trials
- Expert review
Lesson Review - Pass One
- Check identification information
- Content review
- Check boundary conditions
- Examine instructional technique (tutorial, drill, problem solving, game, simulation)
- Technical review
- Supplementary equipment required
- Overall reactions
Lesson Review - Pass Two+
- Content
- Instructional technique (presentation, questions, responses, feedback, remediation)
- Lesson management
- Human factors
- Displays