RE: If You Were Gonna Teach...

["Jane Carnall" <jane -dot- carnall -at- digitalbridges -dot- com>]

Tom Murrell asks:
> But what
I'm really interested in are the four or five things that you would like to
see
your contributors stop doing or do better that would improve both document
writing (Requirements, Designs, etc.) and even email communications.>

1. Not to add their own brand new styles to Word. (This is a Tools thing,
not a writing thing, but there is almost nothing they can do that will cause
me more trouble.)

2. One idea, one sentence. One sentence, one idea.

3. Commas are not rationed. (Seriously, a brief outline of basic punctuation
and how it is used to structure sentences, done in some memorable fashion
with humourous yet accurate examples, would do as much as anything else
would for comprehension.)

4. The difference between company argot, industry jargon, and plain English.

-Company argot is the terms this company has invented for the things it
does. If there is already a generally-understood *within the industry*
jargon term for the same thing, consider using jargon rather than argot.

-Industry jargon is widely understood by people who work in a specific area:
if the document is intended for users within that area, use the jargon term:
if it is intended for newcomers and/or for people outside the area, or if
there is no one generally understood jargon term, include a definition in
plain English.

-"Plain English is language that the intended audience can understand and
act upon from a single reading: see http://www.plainenglish.co.uk/ ."

Jane Carnall
Technical Writer, Digital Bridges, Scotland
Unless stated otherwise, these opinions are mine, and mine alone. Apologies
for the long additional sig: it is added automatically and outwith my
control.


________________________________________________________________________

E-mail is an informal method of communication and may be subject to data corruption, interception and unauthorised amendment for which Digital Bridges Ltd will accept no liability. Therefore, it will normally be inappropriate to rely on information contained on e-mail without obtaining written confirmation.

This e-mail may contain confidential and/or privileged information. If you are not the intended recipient (or have received this e-mail in error) please notify the sender immediately and destroy this e-mail. Any unauthorized copying, disclosure or distribution of the material in this e-mail is strictly forbidden.

________________________________________________________________________


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check it out! Get some cool freebies when you buy RoboHelp! You'll receive
SnagIt screen capture software and a 10% discount voucher for RoboHelp
Consulting. This special offers expires March 29, 2002.
www.ehelp.com/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.