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.
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.
Kathy
k' oooO O oooO O oooO O oooO O wooO O wooO O
o
k-____n_n__====' ---_____ ____________________ ____________________
/___________|__l | ` | OOOOOALOHAOOOOOO | | OOOOEXPRESSOOOOO |
'=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)
