Writing A User Manual (part 1) - Being Conventional (
Page 5 of 5 ) Conventions in the document lead to patterns that the users can grasp.
They then start expecting information in a particular format, thus
increasing their level of comfort with the document. Using consistent
styles also speeds up assimilation of the information, and helps spot
particular information easily on re-reads.
- Headings: Headings are a powerful tool in making a huge mass of text
look manageable. A common model is that as you go deeper in a particular
topic, you indicate that by descending prominence of headings. So, all
top level headings will be, say, in a large font size and bold typeface,
with the next level taking a smaller font size, and so on. You might
also want to number the headings to help users understand the grouping
of information.
- Styles: While a short piece of text requires only minimal use of
styles (bold for highlighting, underline for warning), a tome as
voluminous as a user manual needs you to be much more creative. You
could set conventions for indicating screen names, interface text or
text that the user needs to input.
On the other hand, too many conventions negate the purpose - remember,
they should assist in quick reading and lookup, and they won't if users
have to keep recollecting what a particular style indicates.
- Indented text and footnotes: This is text that is peripheral to the
point that you are making - for example, background information on a
concept that you're introducing or a warning related to some functional
step that you're explaining. Add these when you don't want to distract
the user from the main flow of information.
- Bullets and numbering: Bullets and numbering can also help to break up
complex concepts into simpler, smaller information nuggets. The
convention here is to use numbering for sequential information only (for
example, steps to perform a task) and bullets for other related
information that is best presented in points instead of a paragraph.
Bullets also allow you to group together points related to a concept and
ascribe them levels of importance. Much care and consideration should be
given to the grouping of information in this manner - it could easily be
as confounding as useful.
- Terminology: A very, very important rule of creating end-user
documentation is to be consistent in your use of words. For example, if
you're using the word "function" to indicate the, well, functions of
your software, you shouldn't at any point switch to "features",
"commands", "menu items" or "actions". To this end, make yourself a
glossary of the terms that you're going to use right at the start, and
stick to them consistently.
- Images and illustrations: Sometimes, a picture really is worth a
thousand words - and screen grabs, schematics or flow diagrams can
substantially increase the efficacy of your document. Plan your usage of
images and illustrations in advance, and be consistent in their usage
and labeling.
So that takes care of preparation - all that's left now is to actually
begin work. In the next, and concluding, section, I'll be discussing the
process of actually developing the structure of the manual, together
with a sample table of contents, and also spending some time on document
revisions, version management, and delivery. Make sure you come back for
that!
Note: Examples are illustrative only, and are not meant for a production
environment. Melonfire provides no warranties or support for the source
code described in this article. YMMV!
|
