Docstoc

documentation

Document Sample
documentation Powered By Docstoc
					Documentation
Overview
   What is documentation?
   Getting started
     –   Audience analysis
     –   Tasks vs. procedures
     –   Organizing documentation
   Common sections for documentation
     –   Introduction
     –   Notices
     –   Background or theory
     –   Equipment and supplies
     –   Supplementary information
   Writing style in documentation
   Documenting with graphics
What is documentation?

   Documentation is one of the most common
    and important uses of technical writing.
   Documentation might also be referred to as
    instructions--step-by-step explanations of
    how to do something: how to build, operate,
    repair, or maintain things.
What is documentation?

   Documentation is more complicated than just
    breaking a task down into numbered lists and
    including some examples.
   Successful documentation will include careful
    audience analysis, a thorough understanding
    of what you are documenting, and solid user
    testing.
Getting started: audience analysis

   Define the audience           Be aware that users turn
    and situation of your          to documentation for a
    instructions.                  variety of reasons:
   Defining an audience           –   To learn how to do
    means defining its level           something
    of familiarity with the        –   Because they’ve run into
                                       problems
    topic and the context in
    which the audience will       Assume that no user will
    use the documentation.         want to spend extra time
                                   reading documentation.
Getting started: tasks vs. procedures

   Procedure refers to the      For example, setting
    whole set of activities       the clock on a
    your instructions are         microwave oven is one
    intended to discuss.          task in the big overall
   A task is a semi-             procedure of operating
    independent group of          a microwave oven.
    actions within the
    procedure
Getting started: tasks vs. procedures

   A simple procedure like              Some instructions have only a
    changing the oil in a car             single task, but have many
    contains only one task; there         steps within that single task.
    are no semi-independent              For example, imagine a set of
    groupings of activities.              instructions for assembling a
   A more complex procedure like         kids' swing set.
    using a microwave oven               In this case, group similar and
    contains many semi-                   related steps into phases, and
    independent tasks: setting the        start renumbering the steps at
    clock; setting the power level;       each new phase.
    using the timer; cleaning and        A phase then is a group of
    maintaining the microwave,            similar steps within a single-
    among others.                         task procedure.
Getting started: organizing
documentation

   2 main ways to organize documentation:
    –   Task approach
    –   Tools approach
Getting started: organizing
documentation

   Task approach:
    –   Documentation is organized according to what
        you can do.
    –   For example, in a task approach to instructions on
        using a phone-answering machine, you'd have
        sections on recording your greeting, playing back
        your messages, saving your messages,
        forwarding your messages, deleting your
        messages.
Getting started: organizing
documentation

   Tools approach:
    –   Documentation is organized according to the features of
        tools.
    –   For example, in a tools approach to instructions on using a
        photocopier, there would be sections on the copy button,
        the cancel button, the enlarge/reduce button, the
        collate/staple button, the paper tray, the copy-size button,
        and so on.
    –   Instructions using this tools approach are hard to make
        work. Sometimes, the name of the button doesn't quite
        match the task it is associated with; sometimes you have to
        use more than just the one button to accomplish the task.
Getting started: organizing
documentation

   Listing tasks may not be all that you need to do.
   There may be so many tasks that you must group
    them so that readers can find individual ones more
    easily.
   For example, the following are common task
    groupings in instructions: unpacking and setup tasks;
    installing and customizing tasks; basic operating
    tasks; routine maintenance tasks; troubleshooting
    tasks; and so on.
Common sections for documentation:
introduction

   Plan the introduction to your instructions carefully.
   Indicate the specific tasks or procedure to be explained as well
    as the scope of coverage (what won't be covered).
   Indicate what the audience needs in terms of knowledge and
    background to understand the instructions.
   Give a general idea of the procedure and what it accomplishes.
   Indicate the conditions when these instructions should (or
    should not) be used.
   Give an overview of the contents of the instructions.
Common sections for documentation:
notices

   Documentation often must alert readers to
    the possibility of ruining their equipment,
    screwing up the procedure, and hurting
    themselves.
   Also, documentation must often emphasize
    key points or exceptions.
   For these situations, you use special notices-
    -note, warning, caution, and danger notices.
Common sections for documentation:
background or theory

   Some types of documentation need to
    include a discussion of background related to
    the procedure.
   For example, you may have had some
    experience with those software applets in
    which you define your own colors by nudging
    red, green, and blue slider bars around. To
    really understand what you're doing, you
    need to have some background on color.
Common sections for documentation:
equipment and supplies

   Documentation often includes a list of the
    things you need to gather before you start
    the procedure.
   This includes equipment, the tools you use in
    the procedure (such as mixing bowls,
    spoons, bread pans, hammers, drills, and
    saws) and supplies, the things that are
    consumed in the procedure (such as wood,
    paint, oil, flour, and nails).
Common sections for documentation:
supplementary discussion

   Often users need additional         Make the actual step stand
    explanatory information:             out from the supplementary
    –   how the thing should look        discussion
        before and after the step        –   By bolding the step, or
    –   why they should care about       –   By separating the step from
        doing this step                      the supplementary
    –   what mechanical principle            discussion
        is behind what they are
        doing
    –   the specific actions that
        make up the step
Writing style in documentation

   Documentation use a lot of imperative kinds
    of writing; they use a lot of "you."
    –   "Now, press the Pause button on the front panel
        to stop the display temporarily“
    –   "You should be careful not to ..."
Writing style in documentation

   Do not overuse passive             Do not overuse third
    voice in writing                    person
    documentation                        – "The user should then
   It is easy for the person              press the Pause
    using the documentation                button."
    to miss the point.
    –   "The Pause button
        should be depressed in
        order to stop the display
        temporarily."
    –   "The Timer button is then
        set to 3:00."
Writing style in documentation

   Do not leave out articles
    –   "Press Pause button on front panel to stop display
        of information temporarily.“
   Be sure to include all articles (a, an, the) and
    other such words that you would normally
    use to write complete sentences.
Documenting with graphics

   Graphics are crucial to documentation.
   Words sometimes cannot explain the step.
   Illustrations are often critical to readers'
    ability to visualize what they are supposed to
    do.
More information on documentation

   See PW Online
    –   Documents
           Instructional Documents

				
DOCUMENT INFO