Tech Writing Code of Good Practice

dahmnait · Dec 15, 2006

I make a point to keep myself educated on the Technical Writing field, and in my research today, I ran across this gem. Personally, I think #10 says it best.

Allie · Dec 19, 2006

I personally like using smoke signals as a mode of communication... It's a great oxymoron... it clouds everything and yet sends a clear message.

Good Word · Dec 22, 2006

Thanks, dahmnait!

You know what drives me nuts when I look at tech doc? It's when people try to use more words than necessary just to look more official.

Pet peeve: the word utilize, when use is perfectly acceptable.

ModoReese · Dec 26, 2006

Good Word said:
Pet peeve: the word utilize, when use is perfectly acceptable.

Pet Peeve: The number of managers who have told me to replace use with utilize because "it sounds more technical". I've yet to win a single battle.

I also had the same issue with the phrase "Do you have any spare cycles?" when "Are you busy?" makes the point.

Sorry, got me going there. And I haven't even touched on "tasked" "actioned" or "solutioning".

Good Word · Dec 30, 2006

Another pet peeve:

Using "allows" when "lets" is just fine, and shorter.

Ex.: The --- button lets you... v. The --- button allows you to

EngineerTiger · Jan 3, 2007

Even better..."PUSH the button to turn the unit ON." If you are writing user manuals, keep in mind that the users are often simple people who don't like to read. Active voice over passive voice, folks, when possible.

Very nice list of 10 though. I think I need to print it out for our validation engineers. Sometimes their quality issues get in the way of their communicatin'.

aarthurco · Jan 6, 2007

Love it! I agree with previous poster, I HATE the word utlize...

dahmnait · Jan 18, 2007

EngineerTiger said:
Even better..."PUSH the button to turn the unit ON." If you are writing user manuals, keep in mind that the users are often simple people who don't like to read. Active voice over passive voice, folks, when possible.

This just deserved to be quoted.

EngineerTiger said:
Very nice list of 10 though. I think I need to print it out for our validation engineers. Sometimes their quality issues get in the way of their communicatin'.

Wait a minute....engineers communicate?

RichHelms · Feb 12, 2007

Why not
"To turn on the unit, push the button."

This tells the reader the goal before how to accomplish it.

jdparadise · Feb 14, 2007

RichHelms said:
Why not
"To turn on the unit, push the button."

This tells the reader the goal before how to accomplish it.

I write it as:

To turn on the unit:

1. Push the button.
2. Wait. A prayer to your deity of choice might not hurt.

First, educate the user on what they're doing.

Next, tell them how to do it. Always lead with the instruction; they can read on if they need to.

I do this even for one-step procedures:

To turn on the unit:

Push the button

This approach makes it very clear what the user is doing, and also creates whitespace, which aids comprehension.

Tech Writing Code of Good Practice

dahmnait

Just a figment…

Allie

Good Word

still crazy after all these years

ModoReese

Bang head here for service

Good Word

still crazy after all these years

EngineerTiger

Writing HF Again, Thank God

aarthurco

dahmnait

Just a figment…

RichHelms

@BookTrailer101

jdparadise

Talker of Good Games