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: 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,
you
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
have.
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."
