Re: Golden Rules of Writing

Subject: Re: Golden Rules of Writing
From: Kathy Aloha Nichols <knichols -at- AUSTIN -dot- IBM -dot- COM>
Date: Sat, 7 Jan 1995 00:16:21 GMT

In article <D1xL6I -dot- 5F0 -at- cix -dot- compulink -dot- co -dot- uk>, zulu -at- cix -dot- compulink -dot- co -dot- uk ("Steve
Delanghe") writes:
> >And then there's:
> >
> > "Short words are best and the old words when short
> > are best of all." --Winston Churchill (1874-1965)

> Well here's a few old, short words:

> brevis esse laboro
> obscurus fio

Ah. But don't forget:

"Brevity is the soul of wit."
--William Shakespeare (1564-1616)
"Hamlet", Act II, Scene 2, Line 90

But I was talking about using "plain English" when possible, not
writing documentation so brief as to be cryptic.

> Maybe we should take into account our readers' capabilities! Some people
> think only long new words are worth reading.

There is a difference between readers' opinions and their capabilities.
I've written software documentation for different audiences: end users,
system administrators, and programmers. Using the "cleanest" language
possible for concepts, procedures, and "man page"-type documentation earns
approval from all audiences, believe me. After almost 20 years in the "biz",
you learn one or two things.

It's a shame, but most people are notoriously poor readers (even the
programmers with doctorates). I can't change that fact, nor the fact that the
responsibility for a reader's comprehension of my writing rests 100% with me.
So, I try to follow these simple guidelines:

- Use clear and concise language.
- Avoid excessive jargon.
- Eliminate abstract words or phrases in favor of concrete ones
wherever possible.
- Get rid of deadwood words (e.g., use "regularly" instead of
"on a regular basis")
- Keep sentences short.
- Avoid overuse of the passive voice.
- Use transitional words to connect the "thoughts" in two sentences.
(e.g., ...100% with me. So, I try...).
- Confine paragraphs to a single topic.
- Avoid "haystack" or "grocery list" paragraphs.
- Rewrite "lumpy" paragraphs (where all the technical data is "lumped"
in one long sentence in a paragraph of otherwise short sentences).

And, returning to the original "rules" that spawned this thread, I don't
disagree with the "root" guidelines, that is, make your technical writing:
- Understandable
- Consistent
- Grammatically correct
- Technically correct
I do disagree with all the "unless it interferes" provisos, and I wouldn't
list the items in a hierarchy. I believe all these guidelines are
important, and that good technical writers don't unduly (or deliberately)
sacrifice any one of them for the sake of another.

Aahhhh. I feel much better now.

k' oooO O oooO O oooO O oooO O wooO O wooO O
k-____n_n__====' ---_____ ____________________ ____________________
'=o-o O O O -o-'-~`o-o o-o-~- o-o -------- o-o -~- o-o -------- o-o -
It's a damn poor mind that can only think of one way to spell a word.
--Andrew Jackson (1867-1845)

Previous by Author: Re: Golden Rules of Writing
Next by Author: How about Asimov? (Was: a second for McPhee)
Previous by Thread: Re: Golden Rules of Writing
Next by Thread: Graduate Schools

What this post helpful? Share it with friends and colleagues:

Sponsored Ads