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.
This messages was delayed due to technical difficulties. I hope the person
whose message was forwarded asking about this topic is still around.
Some years back I had a job of teaching programmers to write.
My advice is to determine where the need lies in the writing they're doing
now. In my former job, everything that left the office on paper went past
me first. I saw the same errors over and over again. I designed the course
around those errors. These included:
Problems with parallel structure
Lack of agreement
Between subject and verb, especially when words are interposed
between them
Between adverbs and their antecedents
Dangling modifiers
Excessive use of the passive voice
Sentences bloated with unnecessary words; documents bloated with unnecessary
paragraphs
Taking a long time to get to the point
Poor planning in documents; disregard of the readers and the reader's needs
Vocabulary and usage problems:
A general lack of knowledge about connotation and the shades of meaning to
be found in synonyms, and unfamiliarity with variations in tone
The problems everyone has with affect/effect, continual/continuous and the
like
Phonetic misspellings: "site" for "cite", "manor" for "manner"
A general ignorance of the role of formatting in making the information on
the page more accessible.
I've also detected in many technical people a desire to sound smart-to see
to it that their technical knowledge is on display in what they write,
whether it's appropriate for the task at hand or not. This is especially
true if they believe that other technical people may be reading what they
have written. The way many choose to accomplish this is by larding their
prose with as many acronyms, industry jargon terms and technical terminology
as possible.
I found the approach that was most helpful was to steer clear of rules as
much as possible and to focus on writing as a practical solution for the
practical problem of getting an idea out of one brain and into another. If
something helps deliver the message, that's good; if something interferes
with the message, that's bad.
