TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Steve asks: "Do notes, tips, and warnings really help, or are they just
something we do because we can?"
Your observations about Notes, tips, warnings are dead on! Just as you tend
to ignore them, so, too, do the users who see these things by the railroad
car full. I was told by a user, once , that if I wanted the users to
actually READ notes, tips and warnings and the like, EMBED them in the body
text. Like the sidebars that appear in many college texts, most users
ignore the text we set aside as a note, a tip or a warning. It isn't that
the information isn't important or valid, it's that they have all been there
and done that; even got the T-shirt to prove it.
I find it useful to gauge how my users will regard my documentation by
observing how I use documentation. Like Steve, I also tend to ignore all
the Tips, notes, and warnings. Seen'em a thousand times and, generally,
know what's in them before I scan the first word. So I skip over them.
That's what users do.
Most users use documentation the way that we do. We need to know how to
insert a period at the end of a sentence, so we open the doc, find what we
need, slam the doc closed (sneezing and coughing at the dust cloud that is
raised by slamming it closed) and stick it back on the shelf to gather more
dust. Users, typically, have neither the time, the interest, or the
patience to sit down and read our golden prose from cover to cover. Doesn't
happen.
So, bottom line: If you write docs with tips, notes and warnings and you
want your users to actually read them, make them part of the body text.
Regards,
Pete Sanborn
-----Original Message-----
From: bounce-techwr-l-81537 -at- lists -dot- raycomm -dot- com
[mailto:bounce-techwr-l-81537 -at- lists -dot- raycomm -dot- com]On Behalf Of Steve
Shepard
Sent: Wednesday, November 21, 2001 12:34 PM
To: TECHWR-L
Subject: Notes, tips, and warnings... oh my!
I was thumbing through the November issue of STC's "Technical
Communications" journal and came across the STC International Competition
winners. A comment about one of the winner's struck me: "The strong
navigational aids and highly effective icons and illustrations make
information easy to find and follow." The accompanying figure showed a page
describing a task that was broken up by a "technical note" and a
"definition." Each with lines above and below the paragraph and a large icon
in the margin.
Here is my question: Do notes, tips, and warnings really help the user find
the information he/she needs? Or, do they just break up the flow of
information and make it harder to understand the task being described? When
I read a technical manual and come across these types of things, my eye
generally ignores them and skips over them. On the rare occasion I look at
them, I lose my train of thought and usually have to go back a bit to
refocus.
One of the things I have found irritating in technical documents since the
advent of desktop publishing is the amount of "visual noise" that has been
introduced. Over use of different fonts, busy headers/footer. Lines,
shadings, gradients, etc. Overly ornate bullets, badly designed icons
sprinkled all over the place. You get the idea. In our department we have
worked hard to eliminate visual elements that really don't need to be there.
We try to make things look as clean as possible. Not plain, but clean. As
part of this we stopped using special notes or tips (we kept warnings). We
just felt the they got in the way and that most of the time, and usually it
was information that belonged in the flow of the text, rather than
information that needed to be highlighted.
Do notes, tips, and warnings really help, or are they just something we do
because we can?
And if we don't use them, does that mean we have no hope of winning a
competition? <g>
Steve Shepard
Technical Communications Manager
Yardi Systems, Inc.
819 Reddick Ave.
Santa Barbara, CA 93103
805.966.3822
steves -at- yardi -dot- com
www.yardi.com
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of
your book. What are you waiting for? http://www.iuniverse.com/media/techwr
Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
