Reaching the Right Audience
All of the decisions that you make about the structure and content of a manual follow from an understanding of the audience. You need to think about how the audience accesses the documentation, what sort of information the audience needs, and the experience level of the audience. Usually, you need to create documentation that is suitable for different audiences. The following sections introduce some of the audience-related topics you need to consider.
- 1.4.1. User Motivation
- 1.4.2. New Users
- 1.4.3. Experienced Users
- 1.4.4. Do Not Offend Your Audience
1.4.1. User Motivation
Do not waste the time of the user who looks for information in your documentation. Users do not read technical documentation for entertainment. Users usually have specific questions. You need to give clear answers to those questions.
1.4.2. New Users
New users to the GNOME Desktop are likely to consult online Help for guidance about unfamiliar applications or functionality. Each Help manual should contain enough introductory information to tell new users how to start using the application. Each Help manual should also contain enough usage instructions to tell users the different actions that they can perform with the application. Keep these instructions task-oriented. You do not need to describe GUI screens, dialogs, and dialog elements in Help, unless there is an unusual feature that affects your instructions.
1.4.3. Experienced Users
Experienced users are more likely to use documentation as a reference. The documentation therefore needs to be complete, well-organized, and in the case of printed manuals, well-indexed.
1.4.4. Do Not Offend Your Audience
To avoid offending your readers, apply the following guidelines to your documentation:
- Avoid insider language
-
Insider language includes both undefined jargon and the tendency of the computer community to shorten words. For example, use the term documentation instead of the term docs. You can identify jargon if terminology fails the following conditions:
- A term does not appear in Appendix A ― Recommended Terminology, in this guide.
- A term does not appear in the http://www.bartleby.com/61/.
- A term does not appear in the glossary of the manual that you are writing.
- A term is not defined in the body text of the manual that you are writing.
- Avoid sexist language
-
Pronoun constructions such as his/her or s/he do not exist. There is no need to identify gender in your instructions.
- Avoid culture-specific language
-
There is little point in giving an example that everyone in your town knows about, but is a complete mystery to everyone else in the world.
- Avoid talking down to your reader
-
There are few experiences more irritating for a user than documentation that says an action is easy or quick, when in fact the user cannot complete the action. Do not qualify or prejudge actions.
Other parts of this guide discuss in more detail tone and language usage that can cause offense.