Re: placement and annotation of screen captures in step-by-s

[Suzy Davis <andavis -at- AU1 -dot- IBM -dot- COM>]

Hi Leila

Question One.
I'm a method one girl - and I don't think it confuses readers seeing a screen
before the explanation, it gives them something to refer to while they are
reading the explanation.  With method two the reader is figuring out the
explanation in their head, and then, when they finally see the screen capture,
have to go back and read the explanation again in context (because they
probably got it wrong in their head).

Question Two.
Depends on the complexity of the screen and the screen requirements as to
whether call outs are required.  They can be done without cluttering up the
page.  As to whether you are overestimating the intelligence of your readers -
again, can't tell, give them samples (if you can) and get their feedback).

Apart from that, I think one thing that bad documentation has in common is that
it overestimates the ability of  readers to understand what is being written
and documented (which has nothing to do with intelligence).   Think of all
those manuals that you spent  hours reading, trying to find out how to do
something really urgent, tearing your hair out (a common occurrence - for me -
in the early eighties).  Some manuals seem to be written by insecure technical
writers (who of course may not be technical writers at all but persons like,
analyst/programmers who think they can write) who are trying to demonstrate how
smart they are, and how well they understand the application, which is, of
course, no help to the reader, average or otherwise, at all.  By the way, what
is an average reader?  I don't think they exist.

The reader/user is the only one you and your supervisor should be concerned
about  (financial considerations aside) - and your supervisor seems to be
concerned about them.  Ask whether she has enough experience to know that call
outs are required in this instance.  Presumably she has written manuals and is
basing her opinion on experience, courses she may have completed, and feed back
gathered over years.  You may have experience as well, if so, argue your case.
You may have a personal opinion.  If so, raise it.  Either way, if she/he
doesn't agree, the bottom line is, she/he's your supervisor, and they take the
final responsibility for the work being created, and should be able to ask you
to do the work in a particular way.

Suzy Davis
Technical Writer

Internet:  andavis -at- au1 -dot- ibm -dot- com
[Standard disclaimer]



 TECHWR-L @ LISTSERV.OKSTATE.EDU
 04/14/98 11:07 PM
Please respond to Leila -dot- Meyer -at- MEGASYS -dot- COM

To: TECHWR-L @ LISTSERV.OKSTATE.EDU
cc:
Subject: placement and annotation of screen captures in step-by-step

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

^~~~