Graphics in Text; was Looking for Opinions/Criticism

[Tom Johnson <tjohnson -at- GRANDTRAVERSE -dot- COM>]

Larry Weber wrote:
>
snip

> I've recently started working on a small product in a large software
> corporation and I'm a bit concerned about the usefulness of the Winhelp
> files we provide. It seems to me that the previous writers were more
> concerned about "current trends" such as numbered procedures than the
> actual usefulness of the information.

Larry's original example snipped:

and now a portion of Larry's revised procedure
>
> To access this dialog box, do one of the following:
> · click {bmp of button} on the toolbar
> · from the Search menu click Find String
> · from the shortcut menu click Find String


Larry,

I'm going to dodge the main issue you asked about and point out
something that bothers me. I call it "The Little Red Hen Method." I
disagree with embedding graphics in text (for example _bmp of button_).
"The Little Red Hen" is a children's story where pictures are placed in
the story. Children can, in effect, follow the story by saying the name
of each picture every time an adult reader pauses. It's a great story
and fun to read. Every child should have the opportunity to help read
it.

But, every time I come across a picture in the body of an instruction, I
think of the little red hen and her friends (cat, rat, mouse, cottage by
the woods, cow, scissors, eggs and, of course, the nasty fox that tries
to cook her for dinner). Somehow it seems out of place for a software
help file.

To me, it seems more appropriate to include the name of the button, or
the corresponding menu item rather than to force the reader to switch
gears from text to graphic back to text again. I'll stop short of saying
it looks childish and just say unprofessional. For evidence, think back
to the first time you saw a ;) in an e-mail. You probably thought it was
some kind of typo or wierd punctuation. Until someone told you what it
was a "wink", your mind was thinking text, not graphic. Now that you
know, you are able to switch gears, almost without thinking about it.
The point I'm making is that it takes some effort to switch gears and
can cause some readers to stumble.

If you find it necessary to include a picture of a button in the text, I
would preface it something like this.

"Click the Search button on the tool bar, it looks like this {bmp of
button}."

Putting it at the end of a sentence, or in the sidebar, makes it easy
for someone to skim, just looking for an icon for each step. By the way,
if you do it for one step, you should be consistant and do it for every
step. Having icons in a side bar, for each step, where possible, can be
a great aid. In my printed manuals, I do it all the time and our
customers love it. Many of them are very talented technicians who do not
read well. A lot of them have never used a computer before so icons and
graphics can be particularly helpful.

The reason I'm sensitive about this issue is because I worked on a
project where there were sometimes 10 to 15 graphics used that way on a
single page. It was a real effort to read through the material. Seeing
the cumulative effect made me realize that even one could cause a
problem for some people.

Others may have compelling reasons for putting the graphic in the text
and I would like to hear what they have to say.

Tom Johnson
tjohnson -at- grandtraverse -dot- com

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html