Everyday Tech Writing

Aug 11, 2009 by Lindsay Gower

Technical writing is about procedures and steps in order.  Not all technical writing is about technology. Recipes are technical writing: they’re steps in order, right?  You’ll really mess up the souffle if you put in the Gruyere before you whip the egg whites.

Consider these best practices of technical writing in your every day written communication:

Give warnings up front.
If the sentence contains if,  start the sentence with it.  Most people don’t read instructions completely; they prefer to act rather than to read. Force them to pay attention. They will thank you.

Notice the improvement from the first example to the second:

  • Click the red button if you want to erase everyone on the disk.
  • If you want to erase everything on the disk, click the red button.

Avoid colloquialisms.
Not all of your readers are native English speakers. They can be confused by some of our phrasing. For instances, in American we use like to mean similar to. People less than fluent in American English understand like to mean a level of affection, which makes them puzzle over a sentence such as:

  • The honeysuckle can by pruned like the azaleas.
  • Instead, write: The honeysuckle can be pruned the same way as the azeleas.

Think twice before using any sports metaphor (”… keep it within the ballpark”) unless you are sure your reader will understand. (Notice I said understand instead of get it, because get it is another confusing Americanism.)

Don’t use do not.
Avoid using do not. People will see the do and skip over the not.  (Even don’t has its risks.)  Instead, structure the sentence to be unambiguous. Compare:

  • Do not insert your hand into the lion’s cage.
  • Keep your hands out of the lion’s cage.

Yes, technical writers find employment instructing people how to behave around wild animals. It is truly a jungle out there.


Like this article? You may want to read:

Category: Words & Writing

Tagged: , , ,

Permalink

Leave a Reply

Welcome to The Gold Mine

The Gold Mine is a blog developed by MB/I to assist site owners with the process of developing and maintaining a website. MB/I is a full-service web development company building websites since 2000.

Follow MB/I in: