Re: Basic rules of technical writing

Subject: Re: Basic rules of technical writing
From: CJBenz <cjbenz -at- AOL -dot- COM>
Date: Thu, 22 Dec 1994 17:05:12 -0500

On 21 Dec 1994, lauraj -at- cnd -dot- hp -dot- com (Laura Johnson) wrote:

>: 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!

(Sorry if I'm duplicating myself here. My newsgroup reader is having fits,

and I'm not sure if my last response to this made it to cyberspace...)

Let me ask you this: What good is technical correctness if no one
understands it? Is it good enough to say "Well, it's in the manual and
it's technically correct." Unfortunately, I it happens all too often that
technical correctness gets in the way of successful communication.

BTW, after reading a few comments, I've revised my rules to wit:
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. If that interferes with Rule 1, 2, or 3,
better have a darn good reason.

I think this covers everything now. (Go ahead! Prove me wrong!)

BTW, I write retail-market books, designed to teach beginning users
how to use mostly mainstream software. I also train and design classroom
training materials. This gives me some freedoms that I imagine many
writers--especially those who work closely with software developers--don't
I can, for example.
- ignore poorly designed, useless, weird, and buggy features
- pick and choose what features I want and don't want to cover
- openly criticize software
- do some minor end-user research whenever I want

Chris Benz
Author, Technical Writer, Computer Trainer
6229438 -at- mcimail -dot- com
"You learn something new every day--whether you want to or not."

Previous by Author: Re: Basic rules of technical writing
Next by Author: Re: e-mail or email?
Previous by Thread: Re: Basic rules of technical writing
Next by Thread: Re: Basic rules of technical writing

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

Sponsored Ads