What is good documentation?

The primary function of documentation, whether online documentation or printed, is to help users to do their work quickly and correctly. 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, spring 1999.)

Examples of good documentation and how it can be achieved are in the table:

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 organization (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

Typical problems with documentation

In 1991, the Institute of Scientific and Technical Communicators published Quality and Professionalism in Documentation. The article explained that technical documents frequently have these problems:

Information is missing
The writing is bad and the text is ambiguous
There is a failure to anticipate the readers' problems, questions, and situation
User analysis is not satisfactory. Documents are written for the writers and their situation, not for the readers and their situation
The technical level is not correct
The document structure and the document formatting are bad
The index is bad. The document contains good information, but the information is difficult to find
A professional appearance hides bad content
A document is not changed when a product changes
There is no planning.

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 functions? 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's functions 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 documentation. 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.