Style notes: Difference between revisions
No edit summary |
No edit summary |
||
(12 intermediate revisions by the same user not shown) | |||
Line 17: | Line 17: | ||
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 [[http://blogs.msdn.com/oldnewthing/archive/2003/09/10/54831.aspx here]].) | 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 [[http://blogs.msdn.com/oldnewthing/archive/2003/09/10/54831.aspx here]].) | ||
===For Your Amusement=== | |||
----- | |||
<font size=2 color="#000000" face="Arial"> | <font size=2 color="#000000" face="Arial"> | ||
<div><font size= | <div><font size=4 color="#993300" face="Verdana">Rules</font></div> | ||
<div><font color="#010100" face="Verdana"> | <div><font color="#010100" face="Verdana">are always controversial. But all writers need these things to cling to.</font></div> | ||
<div><font color="#010100" face="Verdana">The following rules make a good litmus test. In general, if you can understand how these sentences break the very rules they promote, | <div><font color="#010100" face="Verdana">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.</font></div> | ||
<div><font color="#010100" face="Verdana">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.</font></div> | <div><font color="#010100" face="Verdana">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. | ||
</font></div><br> | |||
<div><table width="100%" border=0 cellpadding=4 bordercolor="#000000" cellspacing=0> | <div><table width="100%" border=0 cellpadding=4 bordercolor="#000000" cellspacing=0> | ||
<tr valign=top> | <tr valign=top> | ||
<td bgcolor="#ff6600"><font size=2 color="#000000" face="Arial"> | <td bgcolor="#ff6600"><font size=2 color="#000000" face="Arial"> | ||
<div><font size= | <div><font size=2 color="#ffffff" face="Verdana"><b>Writer's Rules, OK ?</b></font></div> | ||
</font> | </font> | ||
</td> | </td> | ||
Line 33: | Line 35: | ||
</table> | </table> | ||
</div> | </div> | ||
<div><font color="#010100" face="Verdana">These rules are normally attributed to William Safire, "the most widely read writer on the English language".</font></div> | <div><font color="#010100" face="Verdana"><br> | ||
<div><font color="#010100" face="Verdana">01. Remember to never split an infinitive.</font></div> | 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. </font></div><br> | ||
<div><font color="#010100" face="Verdana">02. The passive voice should never be used.</font></div> | <div><font color="#010100" face="Verdana">01. Remember to never split an infinitive.</font></div><br> | ||
<div><font color="#010100" face="Verdana">03. Do not put statements in the negative form. </font></div> | <div><font color="#010100" face="Verdana">02. The passive voice should never be used.</font></div><br> | ||
<div><font color="#010100" face="Verdana">04. Verbs have to agree with their subjects. </font></div> | <div><font color="#010100" face="Verdana">03. Do not put statements in the negative form. </font></div><br> | ||
<div><font color="#010100" face="Verdana">05. Proofread carefully to see if you words out.</font></div> | <div><font color="#010100" face="Verdana">04. Verbs have to agree with their subjects. </font></div><br> | ||
<div><font color="#010100" face="Verdana">06. If you reread your work, you can find on rereading a great deal of repetition can be avoided by rereading and editing.</font></div> | <div><font color="#010100" face="Verdana">05. Proofread carefully to see if you words out.</font></div><br> | ||
<div><font color="#010100" face="Verdana">07. A writer must not shift your point of view.</font></div> | <div><font color="#010100" face="Verdana">06. If you reread your work, you can find on rereading a great deal of repetition can be avoided by rereading and editing.</font></div><br> | ||
<div><font color="#010100" face="Verdana">08. And don't start a sentence with a conjunction. </font></div> | <div><font color="#010100" face="Verdana">07. A writer must not shift your point of view.</font></div><br> | ||
<div><font color="#010100" face="Verdana">09. Remember, too, a preposition is a terrible word to end a sentence with.)</font></div> | <div><font color="#010100" face="Verdana">08. And don't start a sentence with a conjunction. </font></div><br> | ||
<div><font color="#010100" face="Verdana">10. Don't overuse exclamation marks !!</font></div> | <div><font color="#010100" face="Verdana">09. Remember, too, a preposition is a terrible word to end a sentence with.)</font></div><br> | ||
<div><font color="#010100" face="Verdana">11. Place pronouns as close as possible, especially in long sentences, as of 10 or more words, to their antecedents.</font></div> | <div><font color="#010100" face="Verdana">10. Don't overuse exclamation marks !!</font></div><br> | ||
<div><font color="#010100" face="Verdana">12. Writing carefully, dangling participles must be avoided.</font></div> | <div><font color="#010100" face="Verdana">11. Place pronouns as close as possible, especially in long sentences, as of 10 or more words, to their antecedents.</font></div><br> | ||
<div><font color="#010100" face="Verdana">13. If any word is improper at the end of a sentence, a linking verb is.</font></div> | <div><font color="#010100" face="Verdana">12. Writing carefully, dangling participles must be avoided.</font></div><br> | ||
<div><font color="#010100" face="Verdana">14. Take the bull by the hand and avoid mixing metaphors. </font></div> | <div><font color="#010100" face="Verdana">13. If any word is improper at the end of a sentence, a linking verb is.</font></div><br> | ||
<div><font color="#010100" face="Verdana">15. Avoid trendy locutions that sound flaky.</font></div> | <div><font color="#010100" face="Verdana">14. Take the bull by the hand and avoid mixing metaphors. </font></div><br> | ||
<div><font color="#010100" face="Verdana">16. Everyone should be careful to use a singular pronoun with singular nouns in their writing.</font></div> | <div><font color="#010100" face="Verdana">15. Avoid trendy locutions that sound flaky.</font></div><br> | ||
<div><font color="#010100" face="Verdana">17. Always pick on the correct idiom.</font></div> | <div><font color="#010100" face="Verdana">16. Everyone should be careful to use a singular pronoun with singular nouns in their writing.</font></div><br> | ||
<div><font color="#010100" face="Verdana">18.The adverb always follows the verb.</font></div> | <div><font color="#010100" face="Verdana">17. Always pick on the correct idiom.</font></div><br> | ||
<div><font color="#010100" face="Verdana">19. Last but not least, avoid clichés like the plague; seek viable alternatives.</font></div> | <div><font color="#010100" face="Verdana">18.The adverb always follows the verb.</font></div><br> | ||
<div><font color="#010100" face="Verdana">19. Last but not least, avoid clichés like the plague; seek viable alternatives.</font></div><br> | |||
<div><table width="100%" border=0 cellpadding=4 bordercolor="#000000" cellspacing=0> | <div><table width="100%" border=0 cellpadding=4 bordercolor="#000000" cellspacing=0> | ||
<tr valign=top> | <tr valign=top> | ||
Line 62: | Line 65: | ||
</table> | </table> | ||
</div> | </div> | ||
<div><font color="#010100" face="Verdana">Unfortunately, life and writing are seldom simple, and despite its obvious brilliance, (7,12,17 in particular) Safire's list has attracted some criticism. </font></div> | <div><font color="#010100" face="Verdana"><br> | ||
Unfortunately, life and writing are seldom simple, and despite its obvious brilliance, (7,12,17 in particular) Safire's list has attracted some criticism. </font></div> | |||
<div><font color="#010100" face="Verdana">4 is particularly controversial, 5 & 6 might be combined, 9 could be "improved" by putting the period outside the bracket, etc.</font></div> | <div><font color="#010100" face="Verdana">4 is particularly controversial, 5 & 6 might be combined, 9 could be "improved" by putting the period outside the bracket, etc.</font></div> | ||
<div><font color="#010100" face="Verdana">Never use a preposition to end a sentence with. | <div><font color="#010100" face="Verdana"> | ||
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. | |||
<div><font color="#010100" face="Verdana"><br></font></div> | <div><font color="#010100" face="Verdana"><br></font></div> | ||
<div><table width="100%" border=0 cellpadding=4 bordercolor="#000000" cellspacing=0> | <div><table width="100%" border=0 cellpadding=4 bordercolor="#000000" cellspacing=0> | ||
Line 106: | Line 113: | ||
</table> | </table> | ||
</div> | </div> | ||
<div><font color="#010100" face="Verdana">George Orwell 1946 reckoned that writers "need rules to rely on when instinct fails". He proposed the following rules. (Slightly modernized here.)</font></div> | <div><font color="#010100" face="Verdana"><br> | ||
George Orwell (1946) reckoned that writers "need rules to rely on when instinct fails". He proposed the following rules. (Slightly modernized here.)</font></div><br> | |||
<div><font color="#010100" face="Verdana">1. Never use a long word where a short one will do.</font></div> | <div><font color="#010100" face="Verdana">1. Never use a long word where a short one will do.</font></div> | ||
<div><font color="#010100" face="Verdana">2. If you can cut a word out, always cut it out.</font></div> | <div><font color="#010100" face="Verdana">2. If you can cut a word out, always cut it out.</font></div> | ||
Line 112: | Line 120: | ||
<div><font color="#010100" face="Verdana">4. Never use a foreign phrase or jargon if there is an everyday English equivalent.</font></div> | <div><font color="#010100" face="Verdana">4. Never use a foreign phrase or jargon if there is an everyday English equivalent.</font></div> | ||
<div><font color="#010100" face="Verdana">5. Never use a metaphor that has become a cliché from overuse.</font></div> | <div><font color="#010100" face="Verdana">5. Never use a metaphor that has become a cliché from overuse.</font></div> | ||
<div><font color="#010100" face="Verdana">6. Break any rule rather than say anything outright barbarous.</font></div> | <div><font color="#010100" face="Verdana">6. Break any rule rather than say anything outright barbarous.</font></div><br> | ||
<div><table width="100%" border=0 cellpadding=4 bordercolor="#000000" cellspacing=0> | <div><table width="100%" border=0 cellpadding=4 bordercolor="#000000" cellspacing=0> | ||
<tr valign=top> | <tr valign=top> | ||
<td bgcolor="#ffcc00"><font size=2 color="#000000" face="Arial"> | <td bgcolor="#ffcc00"><font size=2 color="#000000" face="Arial"> | ||
<br> | |||
<div><font size=3 color="#000000" face="Verdana"><b>Mark Twain</b></font></div> | <div><font size=3 color="#000000" face="Verdana"><b>Mark Twain</b></font></div> | ||
</font> | </font> | ||
Line 122: | Line 131: | ||
</table> | </table> | ||
</div> | </div> | ||
<div><font color="#010100" face="Verdana">Mark Twain wrote (in a letter):</font></div> | <div><font color="#010100" face="Verdana"><br> | ||
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> | ||
<br> | |||
<font size=2 color="#000000" face="Arial"> | |||
<div><font size=5 color="#993300" face="Verdana">Dialog boxes & property sheets</font></div> | |||
<div><font face="Verdana">Dialog boxes contain command buttons and various kinds of options through which users can carry out a particular command or task. For example, in the </font><font face="Verdana"><b>Save As</b></font><font face="Verdana"> dialog box, the user must indicate in which folder and under what name the document should be saved.</font></div> | |||
<div><font size=3 color="#ffffff" face="Verdana"><b>Property sheet</b></font></div> | |||
<div><font face="Verdana">Property sheets display information ("properties") about an object in the interface. For example, the Taskbar property sheet shows information such as the size of the Start menu icons and whether the clock is shown on the taskbar. </font></div> | |||
<div><font face="Verdana"><br></font></div> | |||
<div><font face="Verdana">Property sheets have command buttons and, when properties can be edited, they can contain options, as dialog boxes do. Both dialog boxes and property sheets can have tabbed pages that group similar sets of options or properties.</font></div> | |||
<div><font face="Verdana"><br></font></div> | |||
<div><font size=3 color="#ffffff" face="Verdana"><b>Dialog box</b></font></div> | |||
<div><font face="Verdana">In most documentation, treat elements in dialog boxes and property sheets the same way. Avoid differentiating between property sheets and dialog boxes in end-user documentation. In general, avoid using the term dialog box or property sheet if you can and refer to property sheets as dialog boxes if you can't avoid a descriptor. </font></div> | |||
<div><font face="Verdana"> </font></div> | |||
<div><font face="Verdana">In programming and other technical documentation, buttons and other dialog box elements are called controls, especially in discussions about creating them. Do not use that term in end-user documentation.</font></div> | |||
<div><font face="Verdana"><br></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=3 color="#000000" face="Verdana"><b>Dialog box syntax</b></font></div> | |||
</font> | |||
</td> | |||
</tr> | |||
</table> | |||
</div> | |||
<div><font face="Verdana">These terms are most commonly used for user actions in dialog boxes:</font></div> | |||
<div><font face="Verdana"><br></font></div> | |||
<div><font face="Verdana"><b>Click</b></font><font face="Verdana">: </font><br> | |||
<font face="Verdana">Use for commands, command buttons, option buttons, and options in a list.</font></div> | |||
<div><font face="Verdana"><b>Select </b></font><font face="Verdana">and</font><font face="Verdana"><b> clear</b></font><font face="Verdana">: </font><br> | |||
<font face="Verdana">Use for checkboxes.</font></div> | |||
<div><font face="Verdana"><b>Type </b></font><font face="Verdana">or</font><font face="Verdana"><b> select</b></font><font face="Verdana">: </font><br> | |||
<font face="Verdana">Use to refer to an item (as in a list box) that the user can either type or select in the accompanying text box. You can use enter instead if there's no possibility of confusion.</font></div> | |||
<div><font face="Verdana"><b>Choose </b></font><font face="Verdana">and</font><font face="Verdana"><b> select</b></font><font face="Verdana">: Use these terms only when documenting generic procedures, not mouse procedures. Use choose for commands and select for options.</font></div> | |||
<div><font face="Verdana"><br></font></div> | |||
<div><font face="Verdana">Except for the identifiers box, list, checkbox, and tab, the generic name of an item within a dialog box (button, option, and so on) should not follow the item's label, especially within procedures. Checkbox in particular helps differentiate this item from other option boxes.</font></div> | |||
<div><font face="Verdana">Use bold for dialog box titles, labels, and options.</font></div> | |||
<div><font face="Verdana">The following example shows typical procedure wording for dialog box elements.</font></div> | |||
<div><font face="Verdana"><br></font></div> | |||
<div><font color="#993300" face="Verdana"><b>Correct</b></font></div> | |||
<div><font face="Verdana">To view bookmarks:</font></div> | |||
<div><font face="Verdana">1. On the </font><font face="Verdana"><b>Tools</b></font><font face="Verdana"> menu, click </font><font face="Verdana"><b>Options</b></font><font face="Verdana">, and then click the </font><font face="Verdana"><b>View</b></font><font face="Verdana"> tab.</font></div> | |||
<div><font face="Verdana">2. Select the </font><font face="Verdana"><b>Bookmarks</b></font><font face="Verdana"> checkbox.</font></div> | |||
<div><font face="Verdana"><br></font></div> | |||
<div><table width="100%" border=0 cellpadding=4 bordercolor="#000000" cellspacing=0> | <div><table width="100%" border=0 cellpadding=4 bordercolor="#000000" cellspacing=0> | ||
<tr valign=top> | <tr valign=top> | ||
<td bgcolor="#ffcc00"><font size=2 color="#000000" face="Arial"> | <td bgcolor="#ffcc00"><font size=2 color="#000000" face="Arial"> | ||
<div><font size=3 color="#000000" face="Verdana"><b> | <div><font size=3 color="#000000" face="Verdana"><b>Dialog box elements</b></font></div> | ||
</font> | </font> | ||
</td> | </td> | ||
Line 133: | Line 187: | ||
</table> | </table> | ||
</div> | </div> | ||
<div><font | <div><font face="Verdana">In most documentation, especially for end users, do not differentiate between elements such as </font><font face="Verdana"><i>dropdown combo boxes</i></font><font face="Verdana">, </font><font face="Verdana"><i>list boxes</i></font><font face="Verdana">, and so on. Do use the term </font><font face="Verdana"><i>check box</i></font><font face="Verdana">, however. </font></div> | ||
<div><font face="Verdana">Use the correct label (for example, </font><font face="Verdana"><b>Save as type</b></font><font face="Verdana">) with the term box or list if necessary to locate where the user should be and then direct the user to click, select, or take other action.</font></div> | |||
< | <hr noshade size=4 color="#333399" > | ||
</font> | |||
< | |||
<div><font | <font size=2 color="#000000" face="Arial"> | ||
<div><font size=5 color="#777666" 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="# | <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 | <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="# | <div><font color="#000000" face="Verdana">Most office workers admit an over-reliance on IT support staff.</font></div> | ||
<div><font color="# | <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="# | <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="# | <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><font color="# | <div><table width="100%" border=0 cellpadding=2 bordercolor="#000000" cellspacing=0> | ||
<div><font color="# | <tr valign=top> | ||
<div><font color="# | <td bgcolor="#ffcc00"><font size=1 color="#000000" face="Arial"> | ||
<div>< | <div><font size=2 color="#000000" face="Verdana"><b>Jargon Problems</b></font></div> | ||
< | |||
<div><font | |||
</font> | </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> |
Latest revision as of 11:00, 2 November 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
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.
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.
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.)
Mark Twain
|
Mark Twain wrote (in a letter):
Dialog box syntax
|
Use for commands, command buttons, option buttons, and options in a list.
Use for checkboxes.
Use to refer to an item (as in a list box) that the user can either type or select in the accompanying text box. You can use enter instead if there's no possibility of confusion.
Dialog box elements
|
Jargon Problems
|