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.
re: I know that if I was configuring a large switch network, with several
hundred or possibly thousands of connections, that a WARNING, early on, to
frequently save the configuration file (<save cfg>?) to eliminate the
possible need to do it all over again ...
BAD BAD BAD
This would be misuse of the concept of WARNING. Please avoid misusing
WARNING and CAUTION so as to not contribute to diminishing their
effectiveness. The standard usage in industry is that WARNING is for
situations where the user can be physically (not psychically!) harmed and
CAUTION is for situations where the equipment can be damaged. It *must* be
limited to these eventualities.
Described in the referenced post is a "handy hint" which is best covered in
something just labeled NOTE. I'm personally a little displeased with the
NOTE concept, and if the situation is not one with prescribed rules like the
Military, aircraft industry, etc., I might indeed just label the information
suggested HANDY HINT or GOOD IDEA or TIP or the like. IMHO the NOTE concept
is used too broadly and is therefore usually pretty vague and subject to
just being ignored. This occurs when sometimes the NOTE is a useful hint
but other times it's just background material or expansion of the idea. I
see no danger and indeed better service to the reader in labeling this
material what it is rather than using the vague notion of NOTE.
More: I see another responding post that indicates their style manual
essentially combines rules indicated here for WARNING and CAUTION. Doesn't
seem as safety conscious as possible to me and sugest this be revisited.
re: Speaking from a *software* writer's perspective only, cautions and
warnings are often indicators of where the software is not looking out for
the user. Sometimes this is a design flaw, other times it's specially
planned that way.
Suggest avoiding use of WARNING and CAUTION when writing for software
users--especially if your customer is someone like the Military that also
uses hardware where the generally accepted meanings of these words is
familiar and makes sense in that context and is trained to be second nature.
One might use terms like BE CAREFUL HERE or even WHOOPS!, since these terms
haven't been standardized to the same extent.
WARNING and CAUTION are for instructions for working with hardware. Please.
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.
