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 (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 wrote (in a letter):
"I notice you use plain simple, language, short words, and brief sentences. That is the way to write English."
Dialog boxes & property sheets
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 Save As dialog box, the user must indicate in which folder and under what name the document should be saved.
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.
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.
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.
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.
These terms are most commonly used for user actions in dialog boxes:
Use for commands, command buttons, option buttons, and options in a list.
Select and clear:
Use for checkboxes.
Type or select:
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.
Choose and select: Use these terms only when documenting generic procedures, not mouse procedures. Use choose for commands and select for options.
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.
Use bold for dialog box titles, labels, and options.
The following example shows typical procedure wording for dialog box elements.
To view bookmarks:
1. On the Tools menu, click Options, and then click the View tab.
2. Select the Bookmarks checkbox.
In most documentation, especially for end users, do not differentiate between elements such as dropdown combo boxes, list boxes, and so on. Do use the term check box, however.
Use the correct label (for example, Save as type) 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.
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.
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.
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."