By V. Berba Velasco Jr., Ph.D.
cliché, but true—a picture does paint a thousand words. This is an important
message to remember when writing any sort of user
documentation, such as an installation guide or an instruction
document that makes judicious use of images and diagrams will
be much easier to understand than one that is composed
entirely of text descriptions.
observed this first-hand years ago, when a junior programmer
at one company was asked to update the software installation
manual for their machine controllers. One of the first
things he did was to strip away all the screen capture images,
reducing the entire document to plain text. “These images are just
silly!” he said.
“They take up space, and they’re just not
trust that anyone who reads this document will be smart enough
to figure it out.”
turned out to be a huge mistake. The technicians who
had to use the manual had a difficult time making sense of its
They had to repeatedly ask for clarification, and one
of them told me that the pure text descriptions were just too
cumbersome to follow.
They were fearful of using these instructions at all,
knowing that a single misstep could lock the controllers into
an irrecoverable state.
It was a ugly situation all around.
The problem was that this
programmer didn’t try to make things easy for the users. For one thing, he
failed to consider that some technicians were not native
English speakers, and that they might struggle with the
importantly though, this programmer expected too much from
He wanted to reduce these instructions to their bare
essentials, thinking that would be adequate. He failed to consider
that even an intelligent, otherwise careful reader might be
tempted to jump over instructions, or would gloss over some
critical detail. This is a common pitfall when time is short,
and when the users are confronted with pages and pages of
A few carefully chosen images,
with suitable captions, can go a long way toward preventing
that. When I saw
that the junior programmer was stripping away all the screen
capture images, I cautioned him against that. “These images may not
be strictly necessary,” I said, “but they help clarify a lot
For one thing, they show the user exactly which
button to push, or which window to select. This makes the
instructions much easier to understand, and reduces the
likelihood of a human error.” To this day, I wish
that he had heeded my warning.
Were the users intelligent enough
to understand the manual, as he claimed? Certainly—but
intelligence is no guarantee against human error. Could the images have
been construed as talking down to the user? Perhaps—but in my
experience, sophisticated users seldom respond that way. Rather, most of them
seem to understand the value that these images bring to the
it’s because most of them know what it’s like to be frazzled
and pressed for time, and how easily important details can be
lost in the text.
So remember—a picture paints a
thousand words, and a single screen capture can be worth more
than a dozen pages of text. It’s a lesson that’s
Velasco has a doctorate in Electrical Engineering and has been
practicing his trade for nearly a decade. During that time, he
has repeatedly found that good technical writing skills are
almost as critical as good engineering skills. Dr. Velasco currently
works as a senior electrical and software engineer for
Cellular Technology Limited (http://www.immunospot.com),
a biotech company in Cleveland, Ohio.