Re: Basic rules of technical writing

[Laura Johnson <lauraj -at- CND -dot- HP -dot- COM>]

lmann -at- telerama -dot- lm -dot- com wrote:
: CJBenz (cjbenz -at- aol -dot- com) wrote:
: > Some years ago, a coworker and I hammered out four basic ("golden") rules
: > of writing. To this day, they still work for me, and help solve a variety
: > of conflicts between writers, editors, and what-not. Any comments?

: > The Golden Rules of Writing
: > 1. Make it understandable.
: > 2. Make it consistent, unless that interferes with Rule 1.
: > 3. Make it grammatically correct, unless that interferes with Rule 1 or 2.
: > 4. Make it technically correct, unless that interferes with Rule 1, 2, or
: > 3.

: I wholeheartedly agree with 1, 2, and 3.

: I disagree with 4, depending on the context.

Yeah. My mouth dropped open when I hit 4 and is still hanging open. Some
of my stuff would be a LOT more understandable if I didn't worry about
making it technically correct, but it would also be useless.

I'd keep the list, except that I'd put "technically correct" as #1. In
my world, that's the one you cannot compromise.

I'd love to hear what sort of documentation you're doing, actually. I
have this picture of writers saying "Well, the command syntax the
engineers want us to use is ungrammatical. Let's change it around
for the manual." I'm fairly sure that isn't what you meant!

--
Laura Johnson
lauraj -at- fc -dot- hp -dot- com
Hewlett Packard NSMD
Ft. Collins, CO