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

["Jeanne A. E. DeVoto" <jaed -at- BEST -dot- COM>]

At 2:52 PM -0700 4/14/98, Leila Meyer wrote:
>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 personally don't think it much matters, so long as the illustration is on
the same page (or the facing page) as the instructions. That is absolutely
critical; the exact placement seems to me to be a detail. (Of course, the
instructions need to be written to logically support whichever sequence is
used, as you mention in your examples.)

[supervisor wants callouts over the screen capture]
>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?

Most of my experience is from online instruction, not print, but I will say
that the single Apple Guide feature that was most popular with users - and
that seemed most effective for them - was the "coachmark" feature that
circled the onscreen item that was being referred to. The red coachmark
circle directed their attention immediately to the interface element they
needed to deal with, meaning they could set their attention on *using* it
instead of on locating it.

I think of "clutter" as "non-useful items that are there for decoration",
and this doesn't sound like that. I assume the screen shot has only one
interface element per instruction,so one circle and callout shouldn't
clutter things up much. (You do want to make sure the circle is specced so
it's easy to pick out from the screen shot, using color, a thicker line, a
white-bordered black line, or some other technique.)

One alternative for you might be to use only the portion of the screen shot
that pertains to the instruction, including just enough context that it's
easy for the reader to find the matching area of the screen. This lets the
user focus immediately on the interface element under discussion, the way a
circle on a full screenshot would.

I think you may be barking up the wrong tree with the remark about
"intelligence". Making documentation easier to use is not an insult to the
intelligence of the reader; most people are intelligent enough to read even
badly-organized documentation. But we organize our documentation, we
provide numbered steps, we use screenshots, we use layout, and all the rest
to make it as conceptually simple as possible to figure out the software.
Not because we assume the reader isn't intelligent enough to absorb the
information without these aids; but because our job is to make it not just
possible, but simple.

--
jeanne a. e. devoto ~ jaed -at- best -dot- com
http://www.best.com/~jaed/
Morning people may be respected, but night people are feared.