RE: Using "Tip" and "Note" in procedure writing

["Michele Marques" <marquesm -at- autros -dot- com>]

Walters, Christian writes:

> We're 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.  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.

If those are the appropriate terms for your content and audience, then use
those terms.

I use "tip", "note" and "caution", but they might not be in the same
circumstances as you. I would worry, as you have, that maybe you have too
many of these sorts of styles and that the distinctions are lost on the
audience (or perhaps even on the writers trying to decide which to use!).
For example, when is something a "note" and when is it "important
information"? Whatever you decide, assuming that you work with other
writers, it is important that you explain the appropriate usage in your
style guide, so that they all know when to use them.

I saw one response that indicated that people tend to skip these pieces of
information when not in the normal text flow. I think it depends on your
audience. Some types of information (e.g., a tip) might be best skipped by
someone who doesn't want to deal with extra information now (I put shortcuts
and alternate methods in "tips"). For people who are not reading the text
carefully, styles can help draw attention to certain pieces of information
(e.g., a "caution" or "warning").

Before making these changes, especially getting rid of "caution" and
"warning", check the standards for your audience and type of documentation.
For example, if you are documenting electronic equipment, your UL (or other
certifier) may require you to use "caution" with a particular symbol for
every place where the user could damage the equipment and "warning" for
every place where the user can injure himself or another person.

--------------------------------------------
Michele Marques
Technical Writer,
Autros Healthcare Solutions
marquesm -at- autros -dot- com

This material is intended for the use of the individual to whom it is
addressed and may contain information that is privileged, proprietary,
confidential and exempt from disclosure. If you are not the intended
recipient or the person responsible for delivering the material to the
intended recipient, you are notified that  dissemination, distribution or
copying of this communication is strictly prohibited. If you have received
this communication in error, please contact the sender immediately via
e-mail and destroy this message accordingly.




^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

Sponsored by Information Mapping, Inc., a professional services firm
specializing in Knowledge Management and e-content solutions. See
http://www.infomap.com 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 
http://www.raycomm.com/techwhirl/ for more resources and info.