Style notes: Difference between revisions

From rejetto wiki
Jump to navigation Jump to search
No edit summary
Line 133: Line 133:
Mark Twain wrote (in a letter):</font></div>
Mark Twain wrote (in a letter):</font></div>
<div><font color="#010100" face="Verdana">"I notice you use plain simple, language, short words, and brief sentences. That is the way to write English."</font></div>
<div><font color="#010100" face="Verdana">"I notice you use plain simple, language, short words, and brief sentences. That is the way to write English."</font></div>
<font size=2 color="#000000" face="Arial">
<div><font size=5 color="#993300" face="Verdana">Is documentation important?</font></div>
<div><font face="Verdana">Anyone who doubts the value of good, consistent, documentation might consider the following report taken from the BBC web site (22 September 2005).</font></div>
<div><font size=3 color="#ffffff" face="Verdana"><b>Computer terms 'confuse workers'</b></font></div>
<div><font color="#000000" face="Verdana">Most office workers find computer jargon as difficult to understand as a foreign language, a survey suggests. Three quarters of workers waste more than an hour a week deciphering what a technical term means, the poll found.</font></div>
<div><font color="#000000" face="Verdana">Terms such as jpeg, javascript and cookies are among the problem words highlighted by firm Computer People. The recruiter, which questioned 1,500 workers, says effective technology professionals "understand the need to tailor their levels of jargon".</font></div>
<div><font color="#000000" face="Verdana">Most office workers admit an over-reliance on IT support staff.</font></div>
<div><font color="#000000" face="Verdana">Three quarters of workers waste more than an hour a week deciphering what a technical term means, the poll found.</font></div>
<div><font color="#000000" face="Verdana">The findings revealed that younger workers were just as likely to make a mistake over computer language. It also points to problems which regularly leave workers baffled.</font></div>
<div><font color="#000000" face="Verdana">Just under two thirds had sent e-mails with large attachments which had blocked clients' systems.</font></div>
<div><table width="100%" border=0 cellpadding=4 bordercolor="#000000" cellspacing=0>
<tr valign=top>
<td bgcolor="#ffcc00"><font size=2 color="#000000" face="Arial">
<div><font size=2 color="#000000" face="Verdana"><b>Jargon Problems</b></font></div>
</font>
</td>
</tr>
</table>
</div>
<div><font color="#000000" face="Verdana">An over-reliance on IT staff was admitted by 67% of office workers.</font></div>
<div><font color="#000000" face="Verdana">Logging off instead of re-starting is a mistake made by 14% those surveyed.</font></div>
<div><font color="#000000" face="Verdana">Some 44% of office workers feel it is their duty to improve their IT knowledge.</font></div>
<div><font color="#000000" face="Verdana">More than one in four people are not sure what a firewall does, tempting them to turn it off.</font></div>
<div><font color="#000000" face="Verdana">Turning off firewall - software to protect computers against hackers - is the worst course of action to take, according to IT experts.</font></div>
<div><font color="#000000" face="Verdana">And a quarter of those surveyed had to ask for technical help to download information.</font></div>
<div><font color="#000000" face="Verdana">Mr Fletcher, managing director of Computer People, said: "We're finding that many clients are increasingly requiring professionals who have concise communication expertise as they recognise this improves company productivity in the long run." </font></div>
<div><font color="#0000ff" face="Verdana"><b>Note</b></font><font color="#0000ff" face="Verdana">:</font><font color="#010100" face="Verdana">&nbsp;It's&nbsp;</font><font color="#010100" face="Verdana"><i>web site</i></font><font color="#010100" face="Verdana">&nbsp;not&nbsp;</font><font color="#010100" face="Verdana"><i>Website</i></font><font color="#010100" face="Verdana">.</font></div>
<hr noshade size=4 color="#333399" >
<div align=center><font color="#000000" face="Verdana"> </font></div>
</font>
</body></html>

Revision as of 03:16, 28 October 2006

In general terms, we follow Microsoft guidelines for terminology, as detailed in:
Microsoft® Computer Dictionary, Fifth Edition (Microsoft Press, 05/01/2002).
This establishes basic meanings, spellings and wordforms.

Unfortunately, this has not been updated for more than five years although MicroSoft (MS) terminology changes almost as often as they issue software patches.

More recent glossaries can be accessed through http://www.microsoft.com/resources/glossary/default.mspx.


Some exceptions are noted below:

We use ie. (NOT i.e.) for "that is", and eg. (NOT e.g.) "for example". This violates Microsoft documentation standards, but we like to live dangerously.

We also use etc. as an abbreviation for "et cetera" (it means "and so on"). Curiously, this also violates MS standards, but you'll find many examples of this in their software and documentation.

Like MS, we use both "System tray" and "Notification area" as the name of the right-hand section of the Taskbar that normally includes the clock. (If anyone's actually interested, there's a whole debate about it [here].)

For Your Amusement


Rules
are always controversial. But all writers need these things to cling to.
The following rules make a good litmus test. In general, if you can understand how these sentences break the very rules they promote, you can consider yourself to have mastered English.
The point of many of these sentences is very hard to understand for those who use English as their second language, but mostly obvious to educated natives.


Writer's Rules, OK ?


These rules are normally attributed to William Safire, "the most widely read writer on the English language". In reality, these "Fumble Rules" have a long history and there are many, many variants of these lists. Some may have descended from the "xeroxlore" that circulated throughout campuses and offices in the 1970s.


01. Remember to never split an infinitive.


02. The passive voice should never be used.


03. Do not put statements in the negative form. 


04. Verbs have to agree with their subjects. 


05. Proofread carefully to see if you words out.


06. If you reread your work, you can find on rereading a great deal of repetition can be avoided by rereading and editing.


07. A writer must not shift your point of view.


08. And don't start a sentence with a conjunction. 


09. Remember, too, a preposition is a terrible word to end a sentence with.)


10. Don't overuse exclamation marks !!


11. Place pronouns as close as possible, especially in long sentences, as of 10 or more words, to their antecedents.


12. Writing carefully, dangling participles must be avoided.


13. If any word is improper at the end of a sentence, a linking verb is.


14. Take the bull by the hand and avoid mixing metaphors. 


15. Avoid trendy locutions that sound flaky.


16. Everyone should be careful to use a singular pronoun with singular nouns in their writing.


17. Always pick on the correct idiom.


18.The adverb always follows the verb.


19. Last but not least, avoid clichés like the plague; seek viable alternatives.


Life


Unfortunately, life and writing are seldom simple, and despite its obvious brilliance, (7,12,17 in particular) Safire's list has attracted some criticism. 
4 is particularly controversial, 5 & 6 might be combined, 9 could be "improved" by putting the period outside the bracket, etc.

The following list may also be useful.

       Never use a preposition to end a sentence with.
*
       Avoid anoying alliteration.
*
       Don't verb nouns.
*
       Don't use no double negatives.
*
       Make each pronoun agree with their antecedent.
*
       When dangling, watch your participles.
*
       Don't use commas, which aren't necessary.
*
       Verbs has to agree with their subjects.
*
       About those sentence fragments.
*
       Try to not ever split infinitives.
*
       Its important to use apostrophe's correctly.
*
       Always read what you have written to see if you've any words out.
*
       Correct spelling is esential.
*
       Proofread you writing.
*
       Between you and I, case is important.
*
       Verbs has to agree with their antecedents.


George Orwell


George Orwell (1946) reckoned that writers "need rules to rely on when instinct fails". He proposed the following rules. (Slightly modernized here.)

1. Never use a long word where a short one will do.
2. If you can cut a word out, always cut it out.
3. Never use the passive where you can use the active.
4. Never use a foreign phrase or jargon if there is an everyday English equivalent.
5. Never use a metaphor that has become a cliché from overuse.
6. Break any rule rather than say anything outright barbarous.

Mark Twain


Mark Twain wrote (in a letter):
"I notice you use plain simple, language, short words, and brief sentences. That is the way to write English."


Is documentation important?
Anyone who doubts the value of good, consistent, documentation might consider the following report taken from the BBC web site (22 September 2005).
Computer terms 'confuse workers'
Most office workers find computer jargon as difficult to understand as a foreign language, a survey suggests. Three quarters of workers waste more than an hour a week deciphering what a technical term means, the poll found.
Terms such as jpeg, javascript and cookies are among the problem words highlighted by firm Computer People. The recruiter, which questioned 1,500 workers, says effective technology professionals "understand the need to tailor their levels of jargon".
Most office workers admit an over-reliance on IT support staff.
Three quarters of workers waste more than an hour a week deciphering what a technical term means, the poll found.
The findings revealed that younger workers were just as likely to make a mistake over computer language. It also points to problems which regularly leave workers baffled.
Just under two thirds had sent e-mails with large attachments which had blocked clients' systems.
Jargon Problems

An over-reliance on IT staff was admitted by 67% of office workers.
Logging off instead of re-starting is a mistake made by 14% those surveyed.
Some 44% of office workers feel it is their duty to improve their IT knowledge.
More than one in four people are not sure what a firewall does, tempting them to turn it off.
Turning off firewall - software to protect computers against hackers - is the worst course of action to take, according to IT experts.
And a quarter of those surveyed had to ask for technical help to download information.
Mr Fletcher, managing director of Computer People, said: "We're finding that many clients are increasingly requiring professionals who have concise communication expertise as they recognise this improves company productivity in the long run."
Note: It's web site not Website.

</body></html>