Notes, tips, and warnings... oh my!

Subject: Notes, tips, and warnings... oh my!
From: Steve Shepard <STEVES -at- YARDI -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 21 Nov 2001 09:34:26 -0800

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

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

---
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.


Follow-Ups:

Previous by Author: RE: Microsoft, Monopolies, and Rum
Next by Author: RE: Notes, tips, and warnings... oh my!
Previous by Thread: RE: RE :New department name for training and writing
Next by Thread: RE: Notes, tips, and warnings... oh my!


What this post helpful? Share it with friends and colleagues:


Sponsored Ads