Table of Content
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.
Avoid: ".... five products were reviewed"
Avoid: "Only one product was found to pass all the evaluation criteria."
Writer's Rules, OK?
If you are in doubt about the grammar or general style of your reviews then please make use of our pre-publication editing service where a senior editor will review your copy on request. Just email MidnightCowboy with details and he will arrange the editing.
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:
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:
Unfortunately it omits my favorite Samuel Johnson quote: Only a fool writes for anything but money.
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.
Don't use complicated figures of speech as they are not appropriate here.
Style has two distinct (but irredeemably interdependent) meanings or aspects:
• Physical and mechanical layout details exemplified in a template or produced by a script.
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.
The best general guide to UK English is:
Software category reviews are comparative reviews of a particular *class of software such as "Registry Cleaners." Consequently, reviews should include at least two products (ideally 3) with recommendations. Sometimes it makes sense to say something like: "FamilyClean" is best for beginners, but more experienced users will appreciate the extra features of "FancyClean". For skilled users only, "ScrubUp" is outstanding."
If you only want to review one product, write a Hot Find.
*Editors should take note of these guidelines in relation to beta status products and services.
CPnote> Products expected to be reviewed soon (I can't say "momentarily"!)
Good writing is easy.
It’s just the right words in the right order:
• Use action verbs.
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.
Avoid: "If one were to break Business Intelligence into sub-categories, it would probably be best to do so as such:"
Writers achieve this by applying the following guidelines:
Every occurrence of:
Avoid “We” writing. Do not write, for example, “We will now look at an example of scheduling”.
Users click buttons on toolbars (not icons).
Good documentation is not an accident. It results from a series of good choices, and is based on:
• Effective planning and good writing.
• Heavy use of examples.
• Good illustrative graphics that make the material easier to understand.
• Careful re-iterative review processes.
• Knowing the audience and including the information they need.
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."
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, most of the material on this site will be understandable.
The point of many of these sentences is very hard to understand for those who use English as their second language, but educated natives will understand. However they are a tiny bit obscure otherwise. The key is that they are an attempt to construct a clever sentence that breaks the rule it mentions.
01. Remember to never split an infinitive.
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
A fishmonger had a sign that said: FRESH FISH SOLD HERE
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.
CPnote> You're right of course. It's just a story.
WBW offers the following advice to those inexperienced at writing for the web:
Whatever else you do, don’t:
CPnote> And: Never use an exclamation mark unless you have no alternative. There's always an alternative.
Although it’s not a big issue in the UK, the avoidance of so-called sexist writing is often critical in American contexts. The essential problem (the so-called "generic he”) is shown in the following sentence.
Generally accepted ways to eliminate gender bias include these basic rewrites:
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.
Don’t overuse Please; reserve it for those occasions when you ask users to do something a little unreasonable. For example, “See Section 4.x for more information” is perfectly reasonable; if you write “Please see Section 4.x for more information” you sound a bit desperate. On the other hand, do write, “Please ignore the onscreen message telling you to shutdown that is now displayed”.
That / Which
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.
CPnote> 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
Can / May
Really tiny points
Avoid: “Once you have created the template definition ...”
CPnote> Think we should go with this. It's AP style which is fine by me.
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.
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.
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