Style Guidelines

• Introduction
• Readability
• Style
• Reviews
• Good Writing
• No Accident
• Rule Examples
• Inexperienced Writers
• Sexist Writing
• Please
• Tables
• Tools

Gizmo's encourages a personal chatty style of Review rather than a formal academic style. So try to write in the first person, and use the active voice.
The aim is to produce “Writing that defies misunderstanding.”
Some chance!

Avoid
".... five products were reviewed"
Prefer
"I looked at five products."
Avoid
"Only one product was found to pass all the evaluation criteria."
Prefer
"Only one product did everything I wanted."

Writer's Rules, OK?
These Style Notes attempt to provide guidance and a little stimulation for our Category Editors. They do not represent a set of inhibiting rigid rules. Our visitors are far more interested in what you have to say (the information you wish to exchange), than the way in which you say it.
But all Editors can take advantage of our pre-publication editing service if they wish. Contact Elizabeth (link) for this.

Aim
Gizmo's produces high-quality, informative, comparative reviews of free software to a very diverse audience (many of whom are not native English speakers). This is combined with frank discussion of software. Editors try to act as experienced users offering considered advice or recommendations to a family friend or colleague.

Gizmo's promotes a writing style named Web-based Writing (WBW).
"The Management" encourages this style, but rarely, if ever, attempts to enforce it.
It's the job of the writer to take users from ignorance to understanding, fast.
Some argue that all writing is an “act of rhetoric”; an attempt to persuade someone to do something. WBW attempts to persuade YOU that this writing style will do what you want, is effective, and is easy-to-use.
Break text into small chunks whenever possible. Material displayed on a computer screen is more readable when broken up by lists, tables, bullets, and illustrations.

This Article does not replace standard dictionaries and style books, but concentrates on supplementing and clarifying the information they contain.

Gizmo's ALWAYS welcomes new editors and writers.

600 years of reading print (and all readability studies) teaches us that:
“If it looks difficult to read, it is difficult.”
The first solution is always to shorten sentences.

See here for a wonderful collection of quotes that really drive this point home, from the world's best writers:

http://garbl.home.comcast.net/~garbl/stylemanual/betwrit.htm

Unfortunately it omits my favorite Samuel Johnson quote:
Only a fool writes for anything but money.

Shorten Sentences
In 1978, a respected authority (Barry Turner) advised:
“Restrict the length of a sentence to not more than 35 words, unless it is broken up by semi-colons, etc., into two or more distinct and logical parts.”
Today, WBW could never accept such guidance.
Firstly, used in this way, the semi-colon is almost totally prohibited.
If a sentence can be broken into two “or more distinct and logical parts”, make them separate sentences.
Secondly, WBW suggests typical long sentence lengths as 15-20 words.

Shorten Paragraphs
If paragraphs are too long, they appear difficult.
If they are complicated, they provide too much information for easy understanding.
You can shorten paragraphs by shortening the sentences.

Spelling
This site uses American spelling, so use "center" not "centre", and "disk" not "disc", etc.
In common with most International standards, Americanisms are avoided.

Don't use complicated figures of speech as they are not appropriate here.

pnote>pic here Paradigm Shift
        “Such recognitions are not reversible …”   

Style has two distinct (but irredeemably interdependent) meanings or aspects:

•    Physical and mechanical layout details exemplified in a template or produced by a script.
•    The way words are combined to make sentences and paragraphs.

Style embraces all the traditional topics such as capitalization, punctuation, numbers, reference citations, abbreviations, compound words, and signs and symbols.

The best general guide to American English is Webster's.
There is an excellent online version at:
http://www.websters-online-dictionary.org/
Other versions can be found here:
http://en.wikipedia.org/wiki/Webster%27s
Story
http://en.wikipedia.org/wiki/American_English

The best general guide to UK English is:
http://www.guardian.co.uk/styleguide
Gizmo's speaks American English so you have to slightly modify the "Guardian's" advice.

See also Tools (link)

Structure
Category reviews should generally follow this pattern:

    * This is what these products do, and this is when you might need them.
    * This is my top pick, and here's why.
    * These are some other products to consider with some brief pros and cons.
    * List of related topics on this site.
    * List of specifications for each product reviewed using standard headings.
PHnote> Products expected to be reviewed soon (I can't say "momentarily"!)
Excluded products.
Editor's contact details (webmail)
xref to Forum pages?

•    Use action verbs.
•    Get to the point.
•    Stick to the point.

Bad Writing
Truly bad writing is rarely a matter of grammatical rules; editors can clean these up with a few pencil marks. It's more often the result of muddled thought.

Bad writers consider long words more impressive than short ones, and prefer words like “usage” instead of “use” or “methodologies” instead of “methods”, without really knowing what they mean.

Bad writers qualify everything with phrases like "It has been noted after careful consideration" and the facts get buried under loads of useless words. They pay no attention to the literal sense of their words, and end up stringing stock phrases together without regard for meaning.
They use clichés inappropriately and say the opposite of what they mean.

Avoid
"If one were to break Business Intelligence into sub-categories, it would probably be best to do so as such:"
Prefer
"Business Intelligence sub-categories:"

Good Style
The aim is simply to make the information easy for the reader to use and understand.

Writers achieve this by applying the following guidelines:
•    Common words are used.
•    Abbreviations, acronyms, and symbols are explained.
•    Appropriate technical terminology is adopted.
•    Sentences are short, 18-25 words.
•    Sentences rarely contain parenthetical remarks, semicolons, or colons.
•    Paragraphs are short, averaging 75 words.
•    Bulleted and numbered lists, pictures, and charts occur where appropriate.
•    Overtly informal, sexist, and patronizing language is avoided.

Writer’s Check
Consider carefully, with a view to rewriting or eliminating:
•    Any paragraph that exceeds 10 lines.
•    Every semicolon (except to introduce lists).
•    Any sentence longer than two lines.
•    Every parenthetical expression (but not cross-references).

Every occurrence of:
•    "There is" or "there are."
•    "In order to".
•    "Purpose is to."
•    Herein, therein, hereafter, or whereas.
•    Will, can, may.
•    That is or that are.
•    Which is or which are.
•    One (as in “one can do this”).

Avoid “We” writing. Do not write, for example, “We will now look at an example of scheduling”. 

Users click buttons on toolbars (not icons).
Filenames (note the wordform, it's just one word) are surrounded by "double-quotes".
It's double-click, right-click and click. There is no such thing as a quick or slow click.
It's popup (not pop-up or pop up).
Keystrokes are done like this. "Press <F1> for Help."
List items normally start with a capital letter and end in a period, when they are complete sentences.
Underlining is only used for Hyperlinks.

         
  pnote> pic here “Good artists copy: great artists steal.”  (Pablo Picasso)   

George Orwell
George Orwell 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."

FumbleRules
These rules are normally attributed to William Safire, "the most widely read writer on the English language".

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.

Unfortunately, life and writing are seldom simple, and despite its obvious brilliance, (7,15,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.

Eliminate unnecessary words
This story is sometimes attributed to George Bernard Shaw.
(This concept is explained in book three of "Editing and Design. A Five-Volume Manual of English, Typography and Layout", by Harold Evans.)
A fishmonger had a sign that said: FRESH FISH SOLD HERE
The fishmonger had a friend who persuaded him to rub out [erase] the word FRESH because naturally he wouldn't expect to sell fish that wasn't fresh; to rub out the word HERE because naturally he's selling it here, in the shop; to rub out the word SOLD because naturally he isn't giving it away; and finally to rub out the word FISH because you can smell it a mile off.

CPnote> I don't agree and think that for good usability it is important to make things very clear for all users. If this means the pudding is over-egged for geniuses with perfect eyesight and 24-inch plasma screens, I'm sorry. That's tough.

pnote> You're right of course. It's just a story

CPnote> And: Never use an exclamation mark unless you have no alternative. There's always an alternative.

Generally accepted ways to eliminate gender bias include these basic rewrites:
•    Make the subject and verb plural with plural referents (not “the editor...his”  but “editors...their”).
•    Use “we” or “you” instead of “he”.
•    Use “he or she” (denigrated by WBW).
•    Use “s/he” (denigrated by WBW).
•    Substitute passive voice.

Editors are all too aware that write-around-the-problem strategies present problems of their own, not the least of which is sounding forced. Recasting a sentence into the plural, or using second person instead of third, works well as long as the revision fits in with the surrounding text. But if the discussion has been in the third person, changing persons simply calls attention to the problem without solving it.

Although it's not difficult to find sources that favor using “their” despite the disagreement in number (after all, writers as different as Jane Austen and Ernest Hemingway used it this way), this use is still far more acceptable in spoken than in written language.

One
Do not use One, as in “One must get up early to get everything done”. This construction vanished from contemporary English about 20 years ago (although we let our Queen still use it). You simply have to find a way around it.

That Which
Use of that and which does have reasonably clear grammatical rules, but they are awkward to apply. (See xlink)
The following sentence appears in the Word 2007 Help. “Type any text, including punctuation, that you want to appear after the label.” But the Office 2007 Grammar checker insists that the correct form is: “Type any text, including punctuation, which you want to appear after the label.”
WBW can’t offer any quick solution, but tentatively suggests that "which" is more likely to be correct in most situations.

CPnote> I don't agree. 'That' is used more. 'Which' is mainly used after a comma. You can simply say the following, which is right 90% of the time: "Use 'that' if in doubt. Use 'which' after a comma." The remaining 10% is for students of grammar to get right and we haven't got the time.

pnote> You're right of course. I just don't don't have enough knowledge to know if that works in AE. I'll research. But see MS example above.

Who / whom
is also tricky, and even native speakers often get it wrong. If you’re not sure, use who. You’ll be correct 90% of the time, and most people won’t even notice any error (whereas a misused whom rather catches the eye).

Can / May
The distinction between can and may is really difficult to explain. If you are not sure; use can. May carries a sense of possibility (which may not be fulfilled) and requiring permission. For example, “The user may now finalize rostering” implies that actually, it’s equally probable that the user may not be able to. Prefer “The user can now finalize rostering”. (Even better might be “You can now finalize rostering”.)

Really tiny points
Normally, prefer "when" to "once".
Avoid
“Once you have created the template definition ...”
Prefer
“When you have created the template definition ..."
Whilst
Never use "whilst".

Avoid "folks"
Prefer (your choice) comrades
Although it's easy to use in speech, many educated Americans tend to avoid it in writing.

Avoid
The design of the package is reviewed by the Quality Assurance (QA) Department to determine effective compliance with all and every relevant standard. The contract (s) will be reviewed (normally within three weeks) by the Legal Department and reviewed (normally within four weeks) and endorsed by the Data Process Steering Committee. Signed approval of the acquisition and contract will be by the department head for items under £100,000 (normally within two weeks) and by the division head for items over £100,000 (normally within three weeks). All design specifications must be approved by the EDP auditor (normally within four weeks).

Prefer
This example includes the same information as the paragraph of text above.

pnote> Think we should go with this. It's AP style which is fine by me.

http://garbl.home.comcast.net/~garbl/

Purdue University's Online Writing Lab (OWL) has over 75 handouts, and one of the most extensive collections of advice about writing on the web. Most other sites, instead of providing their own handouts, point to Purdue's.
http://owl.english.purdue.edu/owl/

These handouts are short, but offer plenty of examples. About half address punctuation and grammatical issues and include exercises. Others focus on style, and the writing process. One set of documents (on count and non-count nouns, use of articles and prepositions, etc.) is especially helpful for writers whose first language is not English.

Purdue also provides a wonderful OWL for Business and Professional Writing.
http://owl.trc.purdue.edu/Files/business-writing.html
This has extensive links to resources about business writing including: Writing Report Abstracts, Memo Writing, Sales Letters, Good News and Neutral Messages, Psychological Detail and Dramatization, Adding Emphasis to Writing, Revision in Business Writing, Proofreading, Editing, and Revising.
It also provides Resumes, including extensive links to resources on cover letters, using action words, reference lists, etc., and a discussion on Resources for Job Seekers.

The Collins English Dictionary (8th edition, 2006) is currently considered the best non-academic non-specialist dictionary for British English.

Everything about Dictionaries
http://www.ipl.org/div/subject/browse/ref28.05.00/

Everything about everything else
http://www.refdesk.com/