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.
Personally, comments like "terseness is a no-no in end-user manuals"
sounds like the kind of rule-of-thumb used by poseurs who have no
concept of their audience. People with no sense of audience are
forced to cling to rule-based writing, but they have no way of telling
good rules from bad.
Good technical writing is defined by its results, not its form. If it
tells the reader what he wants to know, when he wants to learn it, and
does so with a minimum of puzzlement, irritation, and false starts,
it's good. If it doesn't, it's bad.
It's been fashionable in some circles to surround the reader with big
puffy clouds of words, presumably to cushion the blow caused by
technical information striking their tiny little end-user brains. My
favorite is still the applications whose on-line help consists
entirely of circular definitions, as in "The File->Save command saves
a file."
Terseness good. Verbosity bad. Sometimes it takes a lot of words to
get a point across, but tossing in an extra bucketful is always bad.
If the description isn't clear, don't pad it -- add diagrams,
examples, or ANYTHING other than big clouds of words to make it clear.
-- Robert
Robert Plamondon * High-Tech Technical Writing
36475 Norton Creek Road * Blodgett OR 97326
541-453-5841 * Fax: 541-453-4139 mailto:robert -at- plamondon -dot- com * http://www.pioneer.net/~robertp
