Re: placement and annotation of screen captures in step-by-step instr uctions for software manuals

[Donna Williams <r3592z -at- EMAIL -dot- SPS -dot- MOT -dot- COM>]

My .04

Re:  First Question

The sequence in Method One is intuitive in that users perform an action and
know what  the result of that action should be.  They immediatley know if they
have performed the action correctly because they know what the screen should
look like.   This is the approach I take with my software user documentation
which has received very positive feedback.

I think Method Two is "trickier" for the users because they don't get the
"visual" until AFTER they perform all of the steps.  There is no "checkpoint"
along the way.  I equate Method Two to the following scenario:

        1)      A parent instructs a child to mow the yard and verbally tells that child
how to
                perform the task.
        2)      Child processes the instructions and mows the yard.
        3)      Parent inspects the yard and finds that child did not perform the task to parent's
                standard.

The child in this scenario (much like a software user)  would have a better
understanding of the assigned task if the parent shows the child how to
perform the task.  The parent could perform a "walkthru" (much like
step-by-step instructions that contain visuals along the way) and point out
what the child needs to accomplish (the required steps) to meet the expected
standard (how well the steps must be performed.)  The Method One approach
reduces the stress and frustration for both parties.

Re:  Second Question

Callouts can be very helpful, but can clutter the diagrams if they are
overused.  If you are providing numbered step-by-step instructions, could you
use call-outs with a number that references a numbered step in the detailed instructions?

Hope this gives you some ideas!
Donna



Leila Meyer wrote:
>
> Hi everyone. I have two questions about screen captures in software
> manuals and would appreciate any insight you can provide into either of
> them.
>
> First Question
>
> In step-by-step instructions where each step applies to a different
> screen (as in software installation instructions and object-oriented
> database navigation) should the screen capture precede or follow the
> related instruction? I have provided two generic examples of
> instructions to illustrate my point.
>
> Method One explains how to reach a screen, then shows the screen, then
> explains what to do with that screen. The advantage of this sequence is
> that it uses a cause and effect approach that (I think) makes logical
> sense. The disadvantage is that it may confuse some readers because they
> see the screen capture in the documentation and don't yet know what to
> do with it. Personally, I prefer this method, and have seen it used in
> other software manuals.
>
> Method Two explains how to reach a screen, then explains what to do with
> that screen, then shows the screen. The advantage of this sequence is
> that a user always knows what to do with a screen by the time they see
> it in the documentation. The disadvantage is that it loses the cause and
> effect logic.
>
> Method One
>
> 1. Run the program. Screen A appears.
>
> <Screen A>
>
> 2. On Screen A, click Next to reach Screen B.
>
> <Screen B>
>
> Method Two
>
> 1. Run the program. Screen A appears.
> 2. On Screen A, click Next to reach screen B.
>
> <Screen A>
>
> 3. On Screen B, . . .
>
> <Screen B>
>
> Second Question
>
> Whenever the user is supposed to click somewhere on the screen, or type
> something into one of the fields on the screen, my supervisor wants me
> to draw a circle on the area of the screen, make a callout pointing to
> the circle, and explain in the callout to "Click Here" or "Type <xyz>
> Here." She wants these call-outs in addition to the regular step-by-step
> explanations. I think that so many circles and call-outs clutters the
> page and suggests that the reader isn't intelligent enough to get the
> necessary information from the numbered steps and accompanying screen
> captures. Am I overestimating the intelligence of the average reader?
> Should I include the call-outs?
>
> Also, if anyone knows of any good books about including screen captures
> in software documentation, I'd love to hear about it. Thanks (in
> advance) for your help.
>
> Leila Meyer
> Technical Writer
> MegaSys Computer Technologies
> leila -dot- meyer -at- megasys -dot- com
>