English Writing Guidelines

A GUIDE FOR THE VEXED
I often help edit papers and reports written by international graduate students who speak and write English as a second language. The hopefully helpful guidelines below are drawn from these experiences. I'm no grammar maven: these are presented in the spirit of practice rather than theory.

DISCLAIMER
* I reserve the right to violate any of the guidelines below.

RECOMMENDED WRITING GUIDES
* "The Elements of Style" by William Strunk and E. B. White is a popular guide to writing American English. It is concise (105 pages),cheap (<$10), and available at any bookstore. E. B. White also wrote several famous books for children. Draw your own conclusions.

* The Chicago Manual of Style is a more complete guideline to word usage, punctuation, etc.

GENERAL ADVICE
* Always re-read and rewrite several times.

* Keep it simple. If your sentences are several lines long with many commas and conjunctions, break them up into shorter pieces.

* Brevity, clarity, and precision are the highest virtues.

* Writing improves with practice. This rule applies to both native and non-native speakers.

* All these rules assume you have something to write. Decide what information you need to convey before you get started. Outlines, notes, and presentations slides are all helpful for organizing your material.

* You must edit and revise often. It is extremely difficult to make an error-free document.

* Recruit others to proofread and critique your writing.

NOUNS AND THEIR ARTICLES
* Nouns (subjects and objects of sentences and phrases) almost always require an article (a, an, or the) when singular. This is a common stumbling block for writers who don't natively speak an Indo-European language.

* Choosing between "a/an" and "the" is not always clear and hard to explain. As a guide,

- Use "the" to refer to something specific. If you can replace "the" in your sentence with "this", "that", "these", or "those", then "the" is appropriate. Also, if a possessive pronoun (his, her, their, my, your) makes sense in front of the noun, then "the" is also appropriate.

- Use "a/an" for a general, unspecified noun.

* Don't overuse proper (capitalized) nouns. These refer to specific people, places, organizations, or activities. For example, "the Internet" is commonly treated as a proper noun, and the Internet Engineering Task Force is the name of an organization, but the general phrase "Internet-based remote invocation protocols" should not be capitalized throughout.

* The distinction between common and proper nouns is sometimes vague, so if in doubt, don't capitalize. If still in doubt, follow precedents from your references.

* When using abbreviations, always put the full name first, followed by the abbreviation in parenthesis. For example, use the format "Community Grids Lab (CGL)".

- You should (almost) never use undefined abbreviations. Even well know ones like "HTTP", "XML", and "URL" should often be defined. You may violate this rule for extremely familiar abbreviations in page-limited papers for an expert audience, but follow it otherwise.

- You should avoid introducing too many new abbreviations. As a rule of thumb, only define your own abbreviations if you must refer to something three or more times in the text and only if you need to save space. This is a useful trick for saving some space in page-limited papers, but it is annoying and should be avoided.

* Be consistent. For example, if you use "Web Services", "Web services", or "web services" in one place in your document, use the same capitalization convention for all other instances.

VERBS AND TENSES
* You should normally use either the present tense ("We research", "We develop") or the present perfect tense ("We have researched..."). Only use past verb tenses when you need to demonstrate the diffence in the present: "We previously developed X 1.0 in the past but have now replaced it with X 2.0".

COMMAS
* Strunk and White can provide rules for using commas. As a general guideline, you use commas in long sentences to tell the reader when to pause and take a mental breath. They are also useful for clarification. Something like "As we have often shown messaging systems which can route SOAP messages are excellent things" can be written "As we have often shown, messaging systems, which can route SOAP messages, are excellent things." Read both versions aloud, pausing briefly at the commas in the second version.

* The sentence above is still terrible. If you find your self writing this way, revise and simplify.

* Don't separate complete sentences with commas (this is called comma-splicing and is one of the deadly sins of grammar). Use periods, semicolons, or colons instead. On second thought, just use periods. Semicolons and colons should be used rarely.

PARAGRAPHS
* A paragraph should be about just one idea. I usually like to keep them short as well. As a general rule, your reader should be able to read paragraph N, ponder what you are talking about, and then read paragraph N+1 without having to re-read paragraph N.

* As another general rule, paragraphs should be at least 3 sentences long.

* If you follow my brevity rule, they should contain at most 5-6 sentences.

BIBLIOGRAPHIES AND REFERENCES
* Only use web sites as references when talking about the actual web site. For example, www.naradabrokering.org and www.globalmmcs.org are NOT references for NaradaBrokering and GlobalMMCS research work.

* Similarly, when referring to IETF, W3C, and OASIS standards, always refer to the document by its full title, authors, and publication date. Don't simply give the URL.

* Collect as many non-lab references for you papers as possible. If Geoffrey Fox is a co-author in every one of your references, reviewers can claim that you have not adequately surveyed the field. Even worse, you may have omitted some of the reviewer's own publications on the subject, which will not please him or her.

MISCELLANEOUS TIPS
* Avoid using "/" to separate words. Common examples include "and/or" and "request/response". This is lazy writing, so don't do this.

* Avoid writing sentences that try to make too many points. A sentence should (as a guideline) make a single point. If you need to make more points, use more sentences.

* Short, crisp sentences are best. Your sentences will meander and drift if you use too many conjunctions and clauses. Always try to make your sentences shorter when you edit.