Effective use of language (was RE: Pet Peeves)

Subject: Effective use of language (was RE: Pet Peeves)
From: Chris Borokowski <athloi -at- yahoo -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Tue, 13 Mar 2007 09:28:06 -0700 (PDT)

This is a great list, and not only for non-native
English speakers. In our busy lives, as we pore over
mountains of documentation while computers and
blackberries and phones beep in the background, we
need simple clarity instead of flowery language. I've
distilled your list a mite further.

- Use short sentences where possible.
- Use present tense where possible.
- Use the simplest possible word where possible,
keeping in mind that oversimplifying loses the nuance
of some words (table versus ottoman).
- Avoid colloquialisms and references to media,
literature, art, sports, food and society. Even within
your native land, not everyone has experienced all of
these things or cares, so you will lose them.
- Avoid news references.
- Avoid humor where confusing. (I cannot become
humorless, and some things are absurd, but if it
detracts from meaning it must go)
- Define terms early in your
presentation/documentation and use them consistently.
- Use parallel structures where they reinforce
- Speak clearly and slowly, enunciating carefully.

Great list. I hope someone puts it in an FAQ.

--- Jonathan West <jwest -at- mvps -dot- org> wrote:

> - Use short sentences.
> - Use present tense wherever possible.
> - Avoid long words except for defined technical
> terms.
> - Avoid colloquialisms.
> - Avoid literary references.
> - Avoid sporting metaphors.
> - Avoid topical references to news items in British
> newspapers.
> - Avoid humor. (Chatting in the coffee break is a
> different matter to formal
> communication.)
> - Where terms have already been defined in the
> standards, use the exact
> wording of the defined term.
> - Speak clearly and slowly, so that people whose
> first language isn't
> English can follow.

We won't tell. Get more on shows you hate to love
(and love to hate): Yahoo! TV's Guilty Pleasures list.

Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include single source authoring, team authoring,
Web-based technology, and PDF output. http://www.DocToHelp.com/TechwrlList

Now shipping: Help &amp; Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up
to 106 languages with Help &amp; Manual: http://www.helpandmanual.com

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.

RE: Pet Peeves: From: Jonathan West

Previous by Author: RE: Pet Peeves
Next by Author: Re: Something a little more useful than: RE: Pet Peeves
Previous by Thread: RE: Pet Peeves
Next by Thread: RE: Pet Peeves

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

Sponsored Ads