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

[CEW -at- MACOLA -dot- COM]

Leila,

I think Method One is the way to go.  If I saw instructions that used
Method Two, I'd think that the author had been one step off in placing
all of the screen shots, and it would frustrate me.  With Method One,
the user is told that "a certain screen appears" and then the picture of
it appears in the doc. immediately following that statement.  This
confirms in the reader's mind that they are on the right screen, which
they need to know before they can think about what they need to do on
that screen.

As far as callouts go, my opinion is that if they're going to be used at
all, they shouldn't be used to repeat what you're going to say in a
step...although if your audience includes people who will use browsing
the doc. as their reading/learning method, callouts may prove
beneficial.   You wondered whether you're "overestimating the
intelligence of the average reader"...I would say, find out what the
intelligence level of *your* readers is.  A little audience analysis
might answer the "should I use callouts?" question.

Connie E. Winch
Technical Writer
Macola Software
Marion, OH USA
cew -at- macola -dot- com


> -----Original Message-----
> From: Leila Meyer [SMTP:Leila -dot- Meyer -at- MEGASYS -dot- COM]
> Sent: Tuesday, April 14, 1998 5:53 PM
> To:   TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
> Subject:      placement and annotation of screen captures in
> step-by-step instr uctions for software manuals
>
> 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
>