Homepage --
Objectives --
Guidelines --
Table of contents --
Advisory board --
Contact us
Documentation: Not yet implemented but coming soon!
Brad Mehlenbacher
- Myths about Documentation
- Nobody reads documentation
- Users don't use it effectively (ie., users are "idiots")
- Documentation is too complex or too limited
- Documentation can't be created until the product is being developed
- Online documentation is hardcopy documentation, only it's online
- Poor documentation doesn't hurt sales or a product's usefulness.
- Transparent interfaces will eventually eliminate documentation
- Putting documentation online solves the problem
- Task-oriented documentation is all that's required
- Guidelines for interfaces and documentation will improve them
- Intelligent agents, speech recognition, wizards, guides, and
gizmos reduce need for support.
- Why is Documentation so Difficult
- Our users/audiences are changing
- Fewer experts
- Fewer users developing expertise
- More transfer users
- More diverse users.
- The purposes for reading are growing
- Reading to do (to perform a task)
- Reading to learn (to learn about something)
- Reading to assess (to figure out the document's contents, usefulness)
- Reading to learn to do (to acquire knowledge for completing
tasks later).
- Our applications are changing
- Creeping featurism and deceptive intuitiveness
- Tasks that depend on support materials
- Bandwidth and peripheral considerations
- The terminologies of technologies
- Multimodal interactions and converging incompatibilites
- Version evolution and legacy challenges.
- Defining Documentation
- By audience knowledge and attributes
- Experience (experts, transfer users, novices)
- Demographics (education, economic, geographic, sub-cultural)
- Learning styles (visual/textual, global/sequential,
reflective/active, ...)
- Literacies (domain, computer, textual, visual)
- Abilities (cognitive, physical)
- Affective attributes (attitude, motivation, engagement).
- By task type
- Representing problems
- Accessing information
- Navigating information
- Scanning information
- Understanding or comprehending information
- Transferring information back to primary tasks.
- By information goal
- Goal exploration (what can I accomplish with this application?)
- Definitional and descriptive (what is this? what is it for?)
- Procedural and immediate (how do I do this?)
- Diagnostic and state explication (what just happened? where am I?)
- Example-based and medium-term (how does this example work?
how do I copy it step-by-step? what are its various parts?)
- Conceptual and long-term (how do all these application
features work together?
what would I like to learn how to do with this application?).
- By physical and rhetorical differences in media
- Resolution
- Display area
- Aspect ratio
- Presence
- Organizational
- Navigational
- Contextual.
- By genre or information type
- Product packaging and labelling
- Getting started guide
- User's guide
- Reference manual
- Read-me files
- Error feedback
- Context-sensitive help messages
- Stand-alone online help
- Tutorial
- Guide, coach, or wizard
- Online documentation.
- Documentation Development
- Needs assessment
- What should our support materials accomplish?
- What are the support materials of our competitors accomplishing?
- What kinds of support can we realistically develop and maintain?
- What features are most and least useful?
- What features are most and least difficult to produce?
- Product specifications
- Audience profiles
- Topic outlines
- Style/design specifications
- Project responsibilities
- Review protocols
- Development schedules
- Cost estimates
- Dependencies and risks
- Sign-off goals.
- Design Goals for support materials
- Accessibility
- Maintainability
- Metaphors and structure
- Support on support
- Organization and consistency
- Navigation and modelessness
- Visual aesthetics
- Levels of explanation and content
- Information fast-tracks (headings, lists, iconic markers, indexes).
- Evaluating support materials
- Forming an evaluation team
- Identifying evaluation goals
- Selecting evaluation methods
- Developing realistic scenarios
- Enlisting real users
- Implementing the evaluation
- Analyzing the data
- Implementing changes.
- Challenges in Documentation: Information Futures
- Collaborative cooperation, diversity, and documentation management
- Large, integrated documents are complex artifacts
- Collaboration requires management, design, and writing
- Work processes, emotional ownership, and revision challenges
- Documentation almost always follows application development
- Ethics, information design, legal and marketing goals.
- Minimalism meets eLearning
- Information delivery, audience, task, and context for use understanding.
- Economic pressures and constraints driving information types and amounts
- Globalization or localization of support materials
- Methods for assessing documenation success.
- Convergence, confusion, and corporate coordination
- Object-oriented applications and support material ownership
- Multimedia, data visualization, and PDA developments
- Internationalization and translation
- Defining where support materials begin and end
- Code developers and programmers versus information developers.
Homepage --
Objectives --
Guidelines --
Table of contents --
Advisory board --
Contact us