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.
In response to Richard Irvine's request for some "Golden Rules" of technical
writing, here are a few off the top of my head:
- Write "task-oriented" documentation (as opposed to function-oriented
documentation), especially when writing procedures manuals.
- Omit needless words, but avoid a compressed, "telegraphic" style, such as
"Press key to reset system." Such writing saves a few words but slows
readers' comprehension. At the same time, writing should be clear, simple,
and concise. (That's a tall order, eh?)
- Write in a modular style. Organize information into "chunks" that build
upon each other. Keep sentence construction simple, and remember that
each paragraph should have only one topic.
- Terminology should be consistent, and synonyms should not be used for
technical terms. For example, always refer to a widget as a widget; do not
call it a widget on one page and then call it a gizmo a few pages later.
Readers may think that a widget and a gizmo are two different things even
if you think they are synonyms.
- Whenever possible, use active rather than passive voice. For example,
passive voice makes this sentence unclear: "If the cause of the problem
cannot be determined, the administrator should be contacted." A better
way to phrase it would be: "Contact your administrator if you cannot
determine the cause of the problem."
- Always define an acronym or abbreviation the first time it is used. Write
it out and put the abbreviation or acronym in parentheses after it when
referring to it for the first time in a document. For example, if you are
writing about File Transfer Protocol (FTP), this is how it would appear in
the first sentence that refers to it. After it is defined, it is no longer
necessary to spell it out each time; simply refer to it as FTP.
- Include a "quality" index for any documentation over 20 pages. A quality
index is:
- consistent in style (capitalization, punctuation, terminology);
- complete (contains entries for all major concepts, definitions,
tasks, and topics);
- well organized, with appropriate subentries under primary entries.
I place a great deal of importance on retrievability and believe that a
quality index is the best retrievability tool. Admittedly, I may be a bit
biased because I am a professional indexer as well as a technical writer.
Hope this info helps.
Lori Lathrop
Lathrop Media Services
Georgetown, CO
(currently on contract assignment to the
U.S. Fish and Wildlife Service, Lakewood, CO)
INTERNET:76620 -dot- 456 -at- compuserve -dot- com
or lathropl -at- mail -dot- fws -dot- gov
