|
Seminars
&
email courses
Technical
Writing & Technical
Writers
“Technical
types underestimate their ability to write”
“The
beauty and utility of language are connected”
“Technical
writers face common problems and challenges”
“To
succeed you need more than technical expertise”
“Technical
writing needn’t be dry”
Top
Seminars &
email courses
Technical types underestimate
their ability to write
By Stephen Wilbers
Author of 1,000 columns
published in the Minneapolis Star Tribune & elsewhere
There’s a
conspiracy afoot in this country, and I’m here to expose it. I take this
action, I might add, at great risk to my professional standing in the
English Majors and/or Teachers Guild of America.
The plot: Convince science-minded people
they can’t write. The subplot: Assure them that if they’re good with their
facts and figures, their incompetence in writing doesn’t matter, that
writing is something only "writers" do. The perpetrators: English majors.
That’s right. Those English majors may
seem like nice, harmless people, but they’re not. They’re nefarious, and
they’re everywhere. Worse yet, they’re learning how to disguise
themselves. Some have exchanged their wire-rimmed glasses for the heavy,
black-rimmed type. Others are wearing plastic pocket protectors stuffed
with silver twist-top pens and mechanical pencils.
But don’t let appearances fool you. They
may act and dress the way you do, but they don’t think the way you do. And
they’re out to undermine your confidence.
William Zinsser first blew their cover
in his 1988 book, Writing To Learn, when he wrote, "The fear of
writing is planted in countless people at an early age -- often,
ironically, by English teachers, who make science-minded kids feel stupid
for not being `good at words,’ just as science teachers make people like
me feel stupid for not being good at science.
"Whichever our type," Zinsser continued,
"the loss of confidence stays with us for the rest of our lives."
The English-major conspirators are
playing games with your mind. They undermine your confidence by placing
unwarranted emphasis on three common deficiencies of scientific and
technical writers:
Fear
You don’t like to write. Never have, never will. That’s the way it’s
supposed to be. You might as well not even try to improve your writing
skills.
Misperception
Writing skills don’t matter. Your true value to your organization is not
what you communicate but what you know. Fussing over style and stylistic
effect, using writing techniques to create special emphasis, or attending
to the sound of language as well as its content is for wimps.
Ignorance
Why waste 10 minutes reviewing the basic conventions of comma placement
when you can make up the rules yourself?
Now, here’s the dirty truth. What the
perpetrators fail to acknowledge are your natural strengths and abilities
as writers. Think about it. Don’t the following traits apply equally to
the science-minded and the language-minded?
*Attention
to specific, concrete detail.
*Ability to think logically and to
present information coherently.
*Recognition that certain rules,
structures, and practices generally produce predictable results.
If the English majors could only get
past their short-sightedness, they might offer you a few basic principles
of good technical writing, such as:
Write
with the reader in mind.
Avoid the content-is-everything fallacy. Define technical jargon for a
broader audience. Identify key terms and concepts.
Know when to use
the active voice and when to use the passive.
Use the active voice to emphasize the performer of the action; use the
passive voice to emphasize the receiver of the action.
Use sentence
structure to your advantage.
Avoid a monotonous succession of long or short sentences. Use a variety of
sentence structures and lengths to create a more vivid, energetic style.
Proofread not
only for accuracy of content but also for correctness of language.
Mechanical errors in language can undermine your credibility in technical
matters.
So if you’re a scientific or technical
writer, take my advice: Beware of English majors. Avoid them at all costs,
both at work and in social settings. They’re out to get you. |
|
Top
Seminars &
email courses
The beauty and utility of language
are connected
By Stephen Wilbers
Author of 1,000 columns
published in the Minneapolis Star Tribune & elsewhere
I was on a plane en route to Atlanta,
reading a story in the newspaper about the Minnesota State Fair, when I
came across this passage: "Fairs
come at the twilight of the year, when the harvest is in and the year’s
work is almost done, when the land prepares for its long winter sleep. The
final event of the departing summer, the Minnesota State Fair marks a time
of celebration, a time of optimism and satisfaction with a job well done.
Like a warm, soft Minnesota night, it is a time of rest and play and
renewal, a time for learning and contemplation and wonder, a time for
dreaming."
With those words, Karal Ann Marling, an
American Studies professor and author of Blue Ribbon: A Social and
Pictorial History of the Minnesota State Fair, did more than describe
the significance of the fair. She also captured the wistful mood of a
passing season.
How did she do it? Why was I so taken
with the passage?
At first I thought it was her rich,
evocative language. But when I read the passage a second time, I realized
it was more than that: It also was the sound of her language.
It was the rhythm and soft cadence of
her sentences. It was the gentle refrain of phrases punctuated by
repetitions of "when" and "a time." One, two. One, two. One, two, three.
And within the last sentence a kind of counterpoint before and after the
repeated phrase: One, two, three. One, two, three. One, two, three. One.
My reason for traveling to Atlanta was
to present a writing workshop to the auditing division of a large
corporation. I would be working with a group of auditors to help them
write their audit reports more effectively. I would be concentrating on
the basics: how to organize and format material for clarity and emphasis,
how to eliminate unnecessary words, how to support important points with
specific detail, and how to avoid common errors.
I would be working, in other words, with
language in a purely utilitarian fashion – or so I thought.
What I had not anticipated, however, was
the eagerness and intensity of the auditors. They asked me questions about
using verbs rather than nouns to write in a more animated style. They
asked me when to use the first person for emphasis and when not to. They
wanted to discuss tone and voice and personality in writing.
During a break I commented on the
group’s enthusiasm to one of the workshop participants.
"We’re a hand-picked group," she
explained. "Most of us will spend about two or three years traveling
around the country doing audits, but we won’t be in these positions for
long.
"This division is our company’s training
ground for future executives. That’s why we’re so interested in what you
have to say about writing. We want to learn anything you can teach us to
help make us more successful in our future positions."
Mystery solved. Here, I thought, was the
antithesis of the stereotypical,
numbers-are-the-only-thing-that-really-counts technical writer. Here was a
group of future executives who understood the importance of developing and
refining their communication skills.
They wanted to know why a sentence such
as "Establishing accounting procedures is one thing; following them is
another" sounded better than "Establishing accounting procedures is one
thing, but compliance has not been consistently achieved." They wanted to
know why balanced sentences had special effect.
The auditors in Atlanta knew something
important. They knew if they could write not only with clarity, but also
with style and personality – even elegance and grace – their futures were
bright. |
|
Top
Seminars &
email courses
Technical writers face common problems
and challenges
By Stephen Wilbers
Author of 1,000 columns
published in the Minneapolis Star Tribune & elsewhere
Technical writers are lousy writers. Harry
is a technical writer. Therefore, Harry is a lousy writer.
There you have it: the syllogism. Major
premise, minor premise, conclusion. The three-step method of
argumentation. The most elementary form of deductive thinking. The
foundation of logical reasoning.
We couldn’t get along without it.
Despite its usefulness, however, the
syllogism has one major shortcoming: If either its major or its minor
premise is false, or if its logic is faulty, its conclusion is invalid.
Is it really true, for instance, that
all technical writers are lousy writers? And does it follow that because
Harry is a technical writer he is necessarily a lousy writer?
Although this particular syllogism is
obviously illogical, many people – including many technical writers –
accept it without question.
To counter this self-limiting
supposition, I offer two points of advice to technical writers: First,
don’t assume that because you are good with numbers you can’t be good with
language. There are too many examples of talented and accomplished
technical writers for this to be true. Outstanding technical writers –
such as Madame Curie, Charles Darwin, Paul Davies, Loren Eiseley, Thomas
Jefferson, Jane Goodall, Stephen Jay Gould, Douglas Hofstadter, Tracy
Kidder, Thomas Kuhn, and Lewis Thomas – come to mind.
Second, don’t underestimate the
importance of competent writing. As J.C. Mathes and Dwight Stevenson point
out in Designing Technical Reports, your value to your organization
is "measured not only by your technical skill and expertise but also by
your ability to present your information in writing that is perceived by
your audience to be useful, relevant, reliable, and persuasive."
On a more practical level, here are
three challenges faced by all technical writers:
Deciding
how much detail to include
Every writer must make decisions of inclusion or omission, but technical
writers, more than others, must make weigh the complexity of their
material against their perception of their reader’s knowledge and
sophistication. The goal – more easily said than done – is to include just
the right amount of detail to get the point across, and not a word more.
Choosing between
the active and the passive voice
Technical writers tend to prefer the passive voice, often for good reason.
They know that the passive voice emphasizes the action performed
("A test well was drilled"), and that the active voice emphasizes the
performer ("Our company drilled a test well").
Many technical writers, however, overuse
the passive voice, embracing it as a matter of habit rather than a matter
of choice. They fail to take advantage of the natural emphasis offered by
the active voice, particularly when their own credibility or judgment
might help sway the reader. Compare, for example, "The recommendation is
made . . ." or "It is recommended . . . " with "We recommend . . ." or "I
recommend . . ."
Remembering to
vary sentence structure and length
Technical writers concentrate on achieving clarity, and rightly so. Their
preoccupation with precision, however, sometimes leads them to neglect the
sound of their language and the rhythm of their sentences.
As a result, they tend to write in a monotonous, plodding style, with one
simple declarative sentence following wearily after another. Compare, for
example, "There was one delay due to an electrical storm. Another delay
was due to a chemical spill" with "There were two delays: one caused by an
electrical storm, the other by a chemical spill."
At the risk of presenting a false
premise or drawing a faulty conclusion, I ask you to consider a second
syllogism: Writers who make negative assumptions regarding their ability
often fail to develop their writing skills. Many technical writers make
negative assumptions regarding their ability. Therefore, many technical
writers fail to develop their writing skills. |
|
Top
Seminars &
email courses
To succeed you need more than
technical expertise
By Stephen Wilbers
Author of 1,000 columns
published in the Minneapolis Star Tribune & elsewhere
A few weeks ago I wrote about the
misconceptions held by writers and editors regarding each other. In
response to that column, one reader wrote:
"I loved your column today on writers and
editors. I particularly appreciated the last two paragraphs [dealing with
types of editing and the natural tension between writers and editors]. . .
"At my work place, the 'natural tension'
between those who write technical and scientific documents and those who
edit is so thick you can cut it with a knife.
"But our conflicts go deeper than
'natural tension. Where I work (and I assume this is probably true of
other organizations) there is a higher value placed on scientific and
technical work than on communication.
"Those who are performing technical and
scientific activities are more respected and much better paid than those
who have skills in editing or crafting messages – regardless of education
and experience. I was wondering whether you have encountered this."
Well, yes, I have. And I suspect other
readers have as well.
In many work-place environments,
technical expertise is more highly valued and rewarded than communication
skills. I would argue, however, that the two are equally important.
Here’s my advice to managers and
technical writers:
Recognize
the importance of good writing.
Unless technical information is communicated effectively, it is of little
value to others. Poor writing undermines the credibility of both the
individual and the organization.
Know your
audience.
A common error on the part of technical writers is to overestimate the
readers’ knowledge of the material and to offer incomplete explanations.
To ensure that you have explained your material adequately for all
readers, write for the educated layperson rather than the fellow expert.
State your
purpose clearly.
This is especially important in technical writing, where your reader may
find the material complex and challenging.
Organize your
material.
Use an outline. Arrange your material logically and sequentially. Consider
using a standard three-part format: introduction/purpose, body, and
conclusion/summary.
Choose the
appropriate method of development.
There are seven basic methods of development: description, example,
process analysis, division and classification, comparison and analogy,
cause and effect, and definition. For explanations and advice on how to
use these methods effectively, see my column titled "Choose method of
development for your writing" under "Column of the month" on my Web page.
Use an
impartial, objective tone.
Technical writing is by nature factual and precise. Avoid subjectivity, an
overly personal tone, and feeble attempts at humor. (For abundant examples
of the latter, see my past columns.)
Keep your
sentences and paragraphs short.
To compensate for the complexity of your material, write in short,
easy-to-understand sentences, and arrange your material in carefully
structured, three-part paragraphs (topic sentence, explanation with
examples, resolution).
Use visuals to
help communicate your message.
You know the cliché: A picture – or a graph or chart – is worth a thousand
words. Be sure to comment on your visuals and to emphasize salient points.
Avoid
misuse of jargon.
There’s nothing wrong with jargon or professional shorthand as long as it
means something more precise than common language and as long as your
reader understands it. A good practice is to define jargon (including
acronyms) on first use.
Do not overuse
the passive voice.
In technical writing, the passive voice often is used to place the
emphasis on the receiver rather than the performer of the
action. For example, the passive "The weld was tested for metal fatigue"
may be preferable to the active "Our engineers tested the weld for metal
fatigue." Nevertheless, look for opportunities to use the more energetic
active voice, as in "The weld showed no signs of metal fatigue." |
|
Top
Seminars &
email courses
Technical writing needn’t be dry
By Stephen Wilbers
Author of 1,000 columns
published in the Minneapolis Star Tribune & elsewhere
Ah, spring in Minnesota. This week we had record-breaking temperatures in
the mid-80s. Last week a snowstorm dumped more than a foot of snow in the
southern part of our state.
But
that’s nothing. A few years earlier – 2.5 million, to be exact – the
Earth’s temperature cooled, the snow stopped melting, and glaciers scraped
and gouged much of the terrain in Minnesota, creating its present network
of lakes, hills, and rivers.
A scientific or technical writer might
describe the phenomenon in this way:
"Four glaciers occurred from 2,500,000
to 10,000 years ago during a geological epoch known as the Pleistocene.
During this epoch cooler temperatures caused snow around Hudson Bay to
stop melting and over time the snow formed a glacier. The glacier started
moving south at the rate of one inch to 10 feet a day. In places the snow
reached a thickness of two miles and its tremendous weight altered the
landscape beneath it."
And the reader might say, "Thanks for
the information, but your writing style, though clear, is dull and
uninviting." And the reader would be right.
The word choice is unexceptional, the
sentence structure monotonous. Note the lack of commas, which usually
indicates a lack of subordinate clauses, as well as the pairing of
sentences around the word and – two common flaws in scientific and
technical writing.
In contrast, consider the following
passage from Paul Lehmberg’s book,
In the Strong Woods: A Season Alone in the
North Country:
"During the last geological epoch
(the Pleistocene – 2,500,000 to 10,000 years ago), Earth’s climate cooled
several degrees and snows in the region of what is now Hudson’s Bay no
longer melted. Piling up layer upon layer, the mass of snow became ice,
and when it reached a thickness of three hundred feet the body of snow and
ice began to move. It had become a glacier."
Note Lehmberg’s variety in sentence
structure, not only in his use of introductory elements marked with
commas, but also in his combination of long-short sentences at the end of
his paragraph. In the next paragraph Lehmberg uses colorful comparisons
and vivid verbs to breathe life into his description:
"Spreading out like batter poured onto a
griddle, it lumbered south over the Canadian Shield and into the Quetico
at the rate of an inch to ten feet a day. By cementing uptorn rock debris
into its snout and underbelly as it heaved down out of the North, the
glacier quarried for itself, cutting, scraping, gouging edges and planes
that completely destroyed existing drainage patterns in its track, and the
sheer weight of one of these icy leviathans, some of which grew to a
thickness of two miles, flattened the crust of the earth."
Then, according to Lehmberg, as the
glacier melted, it didn’t just reveal an altered landscape – it left
behind "a barren profusion of scoured and tortured bedrock littered with
gravel, rocks, and boulders, all awash in the meltwaters of rotting hulks
of ice stranded like whales on a beach. The glaciers had stripped away
intervening Earth history and left exposed a moonscape of Precambrian rock
– rock of the same age as that buried at the bottom of the Grand Canyon."
As illustrated by Lehmberg, technical
writing can be more than precise and informative; it can be vivid and
memorable. |
|
|
|