What is good documentation?
The primary purpose of documentation, whether online or hard copy, is to aid users to perform their work as efficiently as possible. This includes:
- Overcoming problems
- Understanding tasks
- Making decisions
- Performing tasks more efficiently
(The bullet points are taken from 'Beyond Software Manuals and Online Help: Interactive Help', Tony Self, Communicator 6:5, Spring 1999.)
Here are a few examples of what good documentation is and how it can be achieved.
| Good documentation | Achieved through |
|---|---|
| Is appropriate to users' needs | Audience and task analysis, user questionnaires, observation, usability testing of the documentation |
| Contains easily accessible information | Appropriate organisation, meaningful chapter and heading titles, a comprehensive table of contents, consistency of presentation, indexing (even for online material) |
| Reduces costs to your company (case study) | Users finding answers to their questions and thus not calling your helpdesk or other staff |
| Is technically accurate | Technical reviews, usability testing |
| Is linguistically accurate and stylistically consistent | Checklists, style guides, templates, glossaries, controlled languages |
Users' needs
"Users don't want documentation, they want answers" is a well-known phase in documentation circles.
A primary requisite of good documentation is to supply the answers that the user is asking. Fundamental to this is knowing the audience. There is no point in showing expert users of Windows all the screens that appear during the installation of your product. Conversely, computer novices need detailed instructions for many tasks.
Is it better to produce task-based documentation rather than documenting product functionality? Task-based documentation isn't better or worse. It's just different, and it addresses a different need. If users have a set of tasks to perform, they want help with those tasks. A task-based approach directly mirrors this need. There are cases when documenting a product based on its functionality is the right approach. You may need both types of documentation, you may need neither. To decide, you need to know about the users and the tasks they want to perform.
Users have different preferences about documentation. Some users want paper, others want online material. Some users like to know the ideas and concepts behind a product before using it, others want to use the software without preamble. You'll never satisfy everyone, but you can produce documentation that is useful and acceptable to most people if you know your audience.
RSS feed