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:

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

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.

See also

The evolution of user manuals (www.forbes.com/2010/08/07/customer-service-fulkerson-technology-documentation.html)

RSS feed