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

[Leila Meyer <Leila -dot- Meyer -at- MEGASYS -dot- COM>]

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