User Documentation
Documentation for users is an essential part of the user interface that you
provide. It should be as well considered and developed as your application's
user interface. Consider the audience that you address with your product and
tailor the documentation to its needs. It's often useful to provide alternate
types of documentation for the differing types of users who make up your
audience. Beginners have different needs than expert users.
People have distinct learning styles. Some users learn by seeing, some learn
by doing, some learn by hearing, and some learn through a combination of these
styles. It's best to provide for the broadest possible range of learning styles.
For example, including a written tutorial, a written reference manual, an
on-line tutorial with visual and auditory feedback, and an on-line help system
should meet the needs of nearly everyone who wants to learn to use your
product. As an example of an on-line help system, you can look at Balloon Help
in the Finder in system 7.0. For information on including your help system in
the Help menu or implementing Balloon Help for your application, see the Develop task-oriented documentation that teaches users how to accomplish the
tasks that you designed your application to perform. Avoid system-oriented
documentation that describes everything that your application can do rather
than teaching practical skills.
It's important to use standard terminology and nontechnical language in user
documentation. Do not pass on technical jargon to users and expect them to
understand or like it. When you must use technical terms, be sure to define
them at first occurrence, and include a glossary if your document has many
specialized terms. Be consistent in your use of terminology. Make sure that
messages and terms that users see on the screen match what appears in the
documentation.
Apple publishes the Apple Publications Style Guide, which codifies the way in
which Apple documentation uses language. It's a guide to writing about the Apple
Desktop Interface. You can obtain this publication through APDA.
It's very important to translate all user documentation, including tutorials,
on-line help, and books, when you localize your software product. Making your
documentation available in a user's native language greatly enhances the
usability and marketability of your product.