Chapter 12

Team Oahu

Matt Pullen (12.6 & 12.7)
Nathan Matteson (12.1 & 12.2)
Eric Olivarez (12.3 & 12.8)
Byran Diaz (12.4 & 12.5)

Chapter 12 User Documentation and Online Help

12.1 Introduction

12.2 Online Versus Paper Documentation

12.3 Reading from Paper Versus from Displays

12.4 Shaping the Content of the Documentation

Traditional Thoughts

  • Manuals are usually written by junior members.
  • Usually completed at the end of the project.
  • Not suited towards the users background.
  • Either not tested or inadequately done.
  • System developers are not good writers and takes time and skill for effective writing.
  • Users show little interest in reading manuals from cover-to-cover.
  • Users want to focus on gathering information or completing tasks.
  • Users want choices and prefer different types of documentation for different tasks.

“Good online documentation is better than poor paper documentation and good paper documentation is better than poor online documentation.”

12.4.1Towards Minimal Manuals

  • Learners try to make the system work.
  • Read small portions of the manual.
  • Understand the display and explore the functions of the keys.
  • Learners prefer to try actions then read lengthy manuals.
  • Perform meaningful and familiar tasks immediately and see results.
  • These thoughts led to… … … … . .

Minimal Manuals

  • Encourage active involvement with hands-on experience
  • Promote guided exploration of system features
  • Support error recognition and recovery

Visual Aspects

  • Highly helpful with visual direct manipulation and graphical user interfaces.
  • Viewing numerous screen prints that demonstrate typical uses.
  • Develop an understanding and a predictive model of the interface.
  • Users will usually mimic the examples.

Today’s Interactive World

  • Users are becoming technologically sophisticated.
  • Users want to get going quickly with their technology products
  • Advanced electronic systems need extensive training.
  • Easy-to-navigate material with lots of examples
  • Information that is complete, accurate and well organized, and at the right level of technical skill.

Extra Thoughts

  • Authors and designers have become more frequently identified on manuals and products to give credit and recognition.

12.4.2Organization and Writing Styles

Author must be knowledgeable about:

  • Technical Content
  • Sensitive to the background
  • Reading Level
  • Intellectual Ability of the reader
  • Skilled in writing lucid prose

12.5 Accessing the Documentation

  • Studies have confirmed that well-designed documentation can be very effective .
  • Most users would rather skip using manuals and resort to self exploration.
  • IF users read documentation they tend to:
    • Skip
    • Scan
    • Skim

Chapter 12.5.1Online Documentation

  • Manufacturers now put their user documentation online.
    • Browser accessible for no learning required
    • Mobile devices
  • To keep information up-to-date users are able to download manuals from the manufacturers website.

Online Documentation can benefit from physical documentation.
Used manuals have:

  • Dog-ear pages
  • Highlighting
  • Bookmarks

All of which can now be used in programs that provide access to manual documents.

12.5.2Online Help

Users general want help in solving specific problems rather than reading through a full set of online documentation.
Traditionally online help would provide a help-menu item and the system displays a list of alphabetical topics.
Problem – Users who are not sure of the correct terms to use to find needed information.

Complaints about using online help:

  • Trouble navigating the help menu
  • Finding the terminology too technical
  • Difficulty with search strategies
  • Incomplete information provided
  • Too many choices or paths
  • Difficulty with having multiple windows open
  • Too much information

12.5.3Context-Sensitive Help

User-Controlled, Interactive Object Help

  • Monitor the cursor location and provide helpful information about the object under the cursor.
  • Simplest approach is interactive widgets in the interface.
  • Users move the cursor to a location and hover over the object and a small (ToolTip) pop-up box appears with an explanation of that object.

System-Initiated Help

  • Provide effective system guidance
  • Microsoft Office Suite Paper Clip

Hybrid Approaches

  • Intelligent help
  • Advice-giving approach
  • Gives advice and suggestions
  • Focus is on web-site suggestions rather than interface training
  • Requires dedicating a large portion of the display to the help information
  • Keeps users in control of the amount and timing of the advice.

12.5.4Special Populations

“Computer systems and their accompanying documentation are used by a diverse population interacting with a range of applications of differing complexities.”

  • International and cross-cultural Issues
  • Older Adult Users
  • Users with disabilities

International and Cross-Cultural Issues

5 Important Rhetorical Elements:

  1. Purpose
  2. Audience
  3. Content
  4. Organization of the Materials
  5. Style

Also important are:

  1. Differing vocabularies
  2. Eye-movement
  3. Scanning Patterns

Users with Disabilities

Computers have opened up the world to many users with disabilities that severely limited their communication capabilities.

  • Alternative methods of input
  • Switches
  • Head tracking
  • Eye Gazing
  • Voice

Various screen-reader program

  • Freedom Scientific JAWS
  • GW Micro’s Window Eyes
  • IBM’s Home Page Reader

12.6 Online Tutorials and Animated Demonstrations

An online tutorial is an interactive environment in which users can view explanatory descriptions of user-interface objects and actions, often tied to realistic task scenarios.

  • Designing a tutorial
    • Depending on the complexity of the interface
      • Users might be served well by…
      • …an extensive computer based training module
      • …an animated demonstration of features
      • …or a recorded welcome message by a familiar person
    • The challenge often is to prepare materials that will satisfy users who want a 3 minute introduction as well as those who need a 1 hour in depth tutorial

12.6.1 Online Tutorials

  • Online tutorials provide the opportunity for carrying out practice tasks
  • Getting users to be active is one of the key tenets
  • Creators of interactive tutorials must address the usual questions of…
    • …instructional design
    • …the novelty of the computer environment
  • A library of common tasks for users to practice is a great help
  • Help users to experience the application with…
    • Sample Documents for word processors
    • Slides for presentation software
    • Maps for geographic-information systems
  • Repeated testing and refinement is highly recommended for tutorials
  • Start-up Tip
    • Each time the user starts the interface, they get a pop-up box displaying a brief explanation of a feature
    • The user should always be given the option to turn off these tips at any time

12.6.2 Animated demonstrations and multimedia

  • Animated demonstrations have become a modern high-tech art form
  • Originally used to attract potential users of software of hardware by showing off system features using the best animations, color graphics, sound, and information presentation that advertising agencies could produce.
    • They focused on building a positive product image
  • More recently they have become a standard technique to train users as they work
  • The focus is demonstrating step-by-step procedures and explaining the results of the acitons

Animated Demonstration

  • can be prepared as…
    • a slide show
      • appropriate for form fill-in or menu-based interfaces
    • a screen capture animation
      • appropriate to demonstrate direct-manipulation interactions
        • such as drag and drop operations, zoom boxes, or dynamic query sliders
    • A video recording of a person using the device
    • Animated Demonstrations…
      • Easy to produce
      • Can be annotated or narrated
        • Users appreciate recorded voice explanations
        • Providing scripts and subtitles is necessary to address the needs of users with disabilities
      • Have been shown to be more effective at conveying the purpose and use of a tool than a static explanations
      • Users perform tasks faster and more accurately after being shown animated demonstrations rather than textual explanations
      • Reinforce animations with textual explanations
        • Helps user comprehension and retention

12.7 Online Communities for User Assistance

Instead of natural language conversations with computers to get help, interaction with other people online is proving to be effective and popular

This communal approach may employ…

  • e-mail
  • chat
  • instant messaging

…for question asking and responses

  • Communal broadcast approach
    • increasingly appealing because of the low cost to software maintenance organizations and help-desk staff
    • Questions can be sent to a designated help desk or staff member or posted on a discussion board
    • Responses can be received in seconds, or more typically, minutes or hours
      • Respondents get a sense of satisfaction from being able to help others and demonstrate their abilities
      • Some are motivated to achieve prominence withing a community in the hope of gaining consulting contracts


  • recorded common questions and answers into files
  • enables newcomers to browse typical problems that have been discussed in the past
  • often searchable and organized by type of issue or some other hierarchical scheme

Going to the Web for information

  • not all information is correct and valid

Human to human communication removes some of the barriers found with more traditional documentation:

  • Lack of understanding can be handled quickly
  • without consequences of errors

12.8 The Development Process

12.9 Summary

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License