Using "tip" and "note" in procedure writing?

Subject: Using "tip" and "note" in procedure writing?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 1 May 2001 12:34:27 -0400

Christian Walters is <<... still re-working our style guide around here, and
we have a bunch of standards for "tips" and "notes" and "examples" and
"important information" and "cautions" and "warnings," etc. My view is that
the difference between the labels "tip" and "note" and "information," et al,
might be too subtle to be meaningful for the average user.>>

That's probably true to a large extent; nobody should have to learn a
complete etymology before they can even read your docs effectively. I would
note <g> that you do have to preserve a clear distinction between warnings
and the other types of information; if warnings share the same look or feel
as the notes, you risk having users ignore them amidst all the other

<<My solution is to not use those words at all, but replace it with a word
or short phrase that is more descriptive of the actual information --such as
"Prerequisite" or "Admins Only" or whatever.>>

That sounds logical enough, with the above caveats. It's a particularly
interesting approach because the title cues the reader about what to expect,
and provides a particularly clear idea of whether they need to read it.
("Admin? Not me. I can skip it." "Warning? Yup, better read that one.")

<<Anyone know of any studies or other data I can show my cohorts here? I
have yet to brainwash them into simply having blind faith in me :)>>

At the risk of sounding repetitive, I'd suggest the most useful study you
could possibly find would be one that involves your audience--even at the
risk of disproving your own hypotheses about what works. Ask them! Although
you can generally discern important overall principles from published
studies, you have to be very careful to ensure that those studies are
applicable to your specific audience; the devil's always in the details.
It's awfully hard for your cohorts to reject a recommendation based on
demonstrated user needs.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at

"The most likely way for the world to be destroyed, most experts agree, is
by accident. That's where we come in; we're computer professionals. We cause
accidents."-- Nathaniel Borenstein


*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at or info -at- devahelp -dot- com

Sponsored by Information Mapping, Inc., a professional services firm
specializing in Knowledge Management and e-content solutions. See or 800-463-6627 for more about our solutions.

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 for more resources and info.

Previous by Author: Publication layout and other questions?
Next by Author: A question of structure? Two platforms x two user types.
Previous by Thread: RE: FrameMaker Chapter Numbers
Next by Thread: RE: Using "tip" and "note" in procedure writing?

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

Sponsored Ads