- 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:
|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|
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 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 based on its 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 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.
The evolution of user manuals (www.forbes.com/2010/08/07/customer-service-fulkerson-technology-documentation.html)