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.
Subject:RE: "Too many notes! Take some out." From:"Nuckols, Kenneth M" <Kenneth -dot- Nuckols -at- mybrighthouse -dot- com> To:"techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Mon, 19 Dec 2011 12:38:47 +0000
Kevin,
This definitely depends on the type of documentation you're writing, regulations covering your industry, and your audience. If you're writing a manual on jet engine repair for commercial airline mechanics, then probably a healthy dose of notes and cautions and warnings is warranted, based on the consequences of what can happen if someone forgets and only puts 25 bolts back into the engine after they took 26 out... oops!
On the other hand, if you're writing instructions that are going into a box with a router that an individual consumer will add to their home wireless network, then there's not much to worry about physical harm or injury, but a separate section on the importance of using a secure wireless network for identity and data security is probably warranted.
Others have mentioned government-mandated warnings and cautions required by regulations in their industry; if you're working under those conditions you may not have a choice unless rules would permit you to collect those all in an "Important Cautions and Warnings" section as someone else suggested.
But if it's just "nice to know" notes and cautions and warnings that have crept into the documentation over time, then are they really needed? Would those be better in an "additional information" section (maybe not even in the manual, but on a web site for your customers that are real geeks and want to know everything about everything about your product and service).
I work on a team that delivers JIT information to internal agents in a call center and we try to eliminate everything except the exact instructions the employee needs. They're trying to solve a problem for a customer and often already know what to do but just may need a reminder what screens and fields to update on the billing or configuration software. "Nice to know" just isn't very important in that environment--that's information they should know from ongoing training they receive and if they don't remember it at the moment, they don't really need it to fix the problem.
------------------------------
Message: 33
Date: Fri, 16 Dec 2011 14:39:32 -0500
From: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>
To: "techwr-l -at- techwr-l -dot- com" <techwr-l -at- techwr-l -dot- com>
Subject: "Too many notes! Take some out."
Message-ID:
<D1E2C829C5011E4A84DAF8A184DD7CDA01F5F1899A -at- BEL1EXCH02 -dot- amer -dot- sfnt -dot- local>
Content-Type: text/plain; charset="us-ascii"
Anybody recognize where that title came from? :)
Anyway, on a number of topics in my docs, I've found my
pages suffering from Note/Caution/Warning creep.
A few pages have just a paragraph or two of primary
content, and then many times that much of Notes and
cautions. I described in John's "Single H2...." thread how
my Notes are visually set off from text, but at one point
I had eight of the darn things, one following another,
following another, and so on.
For one thing, this gets ugly.
For another, I'd think the reader would begin to develop
Note/Caution fatigue (we have almost no actual warnings),
and lose any capacity to pay attention.
I mean, I know I'm not alone in unceremoniously tossing
those consumer product "User Guide" booklets that
consist of endless cautions and warnings, and no meat.
"Burn before reading..."
What do the rest of you do?
-k
The information contained in this electronic mail transmission
may be privileged and confidential, and therefore, protected
from disclosure. If you have received this communication in
error, please notify us immediately by replying to this
message and deleting it from your computer without copying
or disclosing it.
------------------------------
End of TECHWR-L Digest, Vol 74, Issue 16
****************************************
________________________________
CONFIDENTIALITY NOTICE: This e-mail may contain information that is privileged, confidential or otherwise protected from disclosure. If you are not the intended recipient of this e-mail, please notify the sender immediately by return e-mail, purge it and do not disseminate or copy it.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create and publish documentation through multiple channels with Doc-To-Help.
Choose your authoring formats and get any output you may need. Try
Doc-To-Help, now with MS SharePoint integration, free for 30-days. http://www.doctohelp.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
