What is good documentation?

The primary purpose of documentation, whether online or printed, is to help users to do their work as efficiently as possible. This includes:

Overcoming problems
Understanding tasks
Making decisions
Performing tasks more efficiently.

(The list items are from 'Beyond Software Manuals and Online Help: Interactive Help', Tony Self, Communicator 6:5, Spring 1999.)

Here are some examples of what good documentation is and how it can be achieved.

Attributes of good documentation
Good documentation	Achieved through
Is suitable to users' needs	Audience analysis, task analysis, user questionnaires, observation, usability testing of the documentation
Contains easily accessible information	Suitable organization, meaningful chapter and heading titles, a comprehensive table of contents, consistency of presentation, indexing (even for online material)
Decreases costs to your company (case study)	Users finding answers to their questions and therefore not calling your service desk or other personnel
Is technically accurate	Technical reviews, usability testing
Is grammatically 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 phrase in the documentation profession.

Good documentation answers the questions that people ask. Therefore, you must know the audience. To show expert users of Windows all the screens that appear during the installation of your product is not necessary. However, computer novices need detailed instructions for many tasks.

Is task-based documentation better than documenting product functionality? Task-based documentation is not better or worse. It is only different, and it addresses a different need. If users have a set of tasks to do, they want help with those tasks. Task-based documentation gives them the help that they need. Sometimes, documenting a product based on its functionality is the correct strategy. Possibly, you need both types of documentation, and possibly, you need neither. To decide, you need to know about the users and the tasks they want to do.

Users have different preferences about documentation. Some users want paper, others want online material. Some users want to know the concepts behind a product before they use the product. Other users want to use the software without preamble. You cannot please everyone, but if you know your audience, you can create documentation that is useful and acceptable to most people.