Deliverable Style Guide

From wiki.gpii
Jump to: navigation, search

Writing is easy. All you have to do is
cross out the wrong words.

Mark Twain
What is written without effort
is in general read without pleasure.

Samuel Johnson

Most deliverables in European R&D projects are written by non-native speakers of English. Most deliverables are also harder to read than they need to be. This page contains some guidelines to help improve the readability and grammar of these documents.

A few reminders and notes:

  • This page is work in progress.
  • Most of this page is about British English. If you prefer American or Canadian English, you're on your own (but check out the references at the end of this page).
  • Many native speakers may be used to a more informal writing style. This guide, however, is about academic English and therefore assumes a formal writing style.
  • For advice on citing sources and accessibility, see Cloud4all Deliverable Guidelines.


General Advice

One of the sources of difficult prose is the "curse of knowledge": the inability to imagine that the reader does not know what you know. The following tips can help you exorcise the curse of knowledge:

  • Keep in mind "the reader over your shoulder", i.e. try to imagine what the intended reader knows or does not know.
  • Let a representative reader review a draft of your text. Ideally, this reader is an intelligent person who is not an expert in your field.
  • Leave the text alone for a few months before rereading it. This way, you can be a surrogate for the "representative reader". (Unfortunately, this is not very practical for project deliverables due to the pressure of deadlines.)
  • Read the text aloud. This will help you detect some verbiage and hedging that looks fine on the screen but does not work when read aloud.

Spelling

UK, US or Canadian Spelling

General Guidance

Choose a spelling convention and stick to it throughout the document. Make sure that the document's language setting matches the spelling convention you have chosen. In Microsoft Word you can check the language setting in the status bar below the editing area. You can make sure that the language setting is consistent throughout the document by pressing Control+A (to select all the content) and selecting the appropriate language under Review > Language > Set Proofing Language...

Setting the document language correctly also enables Word to check the spelling of words (red wavy underlines).

For guidance on British spelling and punctuation, please refer to a guide like the MHRA Style Guide, which can be downloaded for free. For the spelling of specific words, use any up-to-date dictionary.

Examples

-our versus -or

UK spelling: (foreground) colour, ... US spelling: (foreground) color, ...

-er versus -re

UK spelling: centre, home theatre, ... US spelling: center, home theater, ...

-ce versus -se
  • UK spelling: a licence, to license (or to licence), practice makes perfect, to practise, ...
  • US spelling: a license, to license, practice makes perfect, to practice, ...

However, when citing the title of a specific licence, use the spelling used by that licence, e.g. "the General Public License (GPL), version 3.0".

-ise/-yse versus -ize/-yze
  • UK spelling: customise, initialisation, organisation, analyse, ...
  • US spelling: customize, initialization, organization, analyze, ...

Note: many organisations in the UK use the spelling with '-ize' and '-ization'. This is known as Oxford spelling or OED spelling. However, this does not affect the spelling of analyse!

-ll- versus -l-
  • UK spelling: modelling, modelled, ...
  • US spelling: modeling, modeled, ...
-e- in ageing, gamification, ...

Notes:

  • Many -ing forms have been accepted as adjectives and don't have in 'e' in British English, e.g. in "a raging thirst".
  • Sometimes, there is a difference in meaning: singing comes form the verb 'to sing', while singeing comes from the verb 'to singe' (to burn slightly).

Frequently Misspelled Words

  • screen reader (always written with a space)
  • to fulfil (fulfilled); US: to fulfill

Capitalisation (Upper Case or Lower Case)

The following rules are not exhaustive but should be sufficient for writing deliverables. Capitalise:

  • names of people, places, organisations, institutions
  • months and days of the week
  • titles of documents (books, deliverables) and journals

Do not capitalise:

  • nouns (e.g. project, deliverable, report, social network, ...)
  • in titles: prepositions (in, at, for) shorter than five letters, and articles (a, an, the), except when they are the first word in a title

There is no consensus on:

  • Internet or internet (a place or a technology?)
  • the Web & the World Wide Web or the web & the world wide web

Examples from deliverables:

  • "this Deliverable" -> "this deliverable". The word "deliverable" is not a title but an ordinary noun.
  • "... to access the Social Networks" -> "... to access (the) social networks"
  • "the Remote Control" -> "the remote control"
  • "He uses Hotmail for emails, google docs for documents, ..." -> "He uses Hotmail for emails, Google Docs for ...": Hotmail and Google Docs are names.
  • Examples of unusual capitalisation: TalkBack (Android feature), WebAnywhere (web-based screen reader), ...

The Economist's Style Guide contains detailed guidance on capitals.

Hyphens Versus One Word or Separate Words

The hyphen or dash is used:

  • in (attributive) adjectives formed from two or more words, e.g. a well-researched paper, a 30-year-old pilot, but not necessarily in predicative adjectives, e.g. "this paper is well researched" (see Attributive and Predicative Adjectives)
  • in most words that begin with anti, counter, half, inter, non and semi
  • in ex- when it means 'former': ex-wife
  • to replace 'and', e.g. "the Myers-Briggs Type Indicator"
  • to avoid ambiguity; example:
    • a "heavy metal detector" is a heavy detector made of metal, while a "heavy-metal detector" is a detector of heavy metals (example borrowed from Grammar Monster);
    • "re-sign" means to sign again, "resign" means to quit a job or position;
    • "re-cover" means to provide with a new cover, "recover" means to get well again.
  • to avoid a confusing sequence of letters, e.g. "re-enter a password", "pre-echo", "pre-eminent" (but the hyphen is usually not needed in words with pre- followed by a consonant, e.g. prepaid)
  • in compounds containing the same "head", e.g. "cloud- and web-based" (note the "hanging hyphen" after 'cloud')

This is not a full list. The Economists' Style Guide gives more rules and examples. When in doubt, consult a dictionary.

Many new terms start out as two words, then become hyphenated, and finally become accepted as a single word. In some cases, there is no consensus whether a term should be written with a hyphen or as one word. For example, most words starting with "auto" are written as one word, but "auto-suggestion" is written with a hyphen in the Oxford Advanced Learner's Dictionary but as one word in the Collins English Dictionary and the Cambridge Dictionary Online.

Examples from deliverables:

  • "low-vision users" (though the phrase "users with low vision" is more correct)
  • "a multi-user application"
  • "Web-based screen reader" (needs a hyphen because "Web-based" is used as an attribute)

Examples of words written with a hyphen:

  • fine-tune
  • hands-on demonstration/training/...
  • hearing-impaired (some dictionaries list "hearing impaired" as an alternative)
  • real-life scenarios/footage/...
  • real-time (as an attribute; derived from the noun "real time")
  • well-known
  • cost-benefit analysis
  • a step-by-step approach (because used as an adjective; compare: "we will proceed step by step")

Examples of words without a space or hyphen:

  • deafblind (adjective)
  • workflow
  • smartphone
  • prepilot (though some spelling correctors prefer "pre-pilot")
  • pretest (Oxford and Collins; Cambridge also accepts pre-test)
  • shortcut (noun and verb; Collins also allow the hyphen in the verb: short-cut / shorcut)
  • multimodal

Examples of words with a space:

  • end user (however, when the phrase is used as a modifier, you add a hyphen, e.g. "end-user experience")
  • screen reader
  • smart house
  • task force
  • data type
  • value space

Special cases:

  • e-mail / email: There is no consensus on the spelling of "e-mail" or "email", but the spelling without the hyphen tends to be favoured.
    (See Email: Spelling (Wikipedia), "Think hyphens aren't contro-versial? Think again" (The Guardian, 4 April 2011), University of York: Style Guide, University of East Anglia: Writing Style Guide.)
  • run time (Collins) / run-time (Cambridge, which also allows "runtime") / runtime (Oxford). However, when used as an adjective before a noun, the spelling is either run-time or runtime: e.g. a run-time environment / a runtime environment.
  • "front end" versus "front-end":
    • "front end" and "back end" (without a hyphen) are nouns, e.g. "the front end of a mobile application", "the back end of the server";
    • "front-end" and "back-end" (with a hyphen) are used attributively (see above), e.g. "a front-end fee" (=paid in advance).

Punctuation

Comma

The comma is used in the following situations:

  • To replace "and" or "or" in an enumeration or a similar series of items, e.g.:
    • "The guidelines do not cover the needs of people with all types, degrees and combinations of disabilities."
    • "George shot the video, Maria added captions to it and Ignacio uploaded it to the server."
    • Note: American English places a comma before the final "and". British English only places a comma before the final "and" when the penultimate item in the list includes another "and". For example:
      • "He ordered coffee, bacon and eggs, and toast."
  • To combine two sentences into a single one by means of a conjunction such as "but", "yet", "while" or "so":
    • "The first evaluation phase will experience some delay, but this will not affect the next phases."
    • Note: If the subject of the second sentence is omitted, or if the conjunction is "and" or "or", the comma is not obligatory. For example:
      • "The peer reviewers found the deliverable unsatisfactory(,) but did not give advice on how to improve the document."
      • "The peer reviewers proposed several changes to improve the deliverable(,) and the authors followed the proposals."
  • After an introductory adverb (e.g. "nevertheless", "however", "suddenly"), an introductory phrase or a parenthetical phrase:
    • "Surface and ground water are two separate entities, so they must be regarded as such. However, there is an ever-increasing need for management of the two ..."
    • "In Windows, for example, you can choose between different desktop themes."
      • Note: "For example" is not always a parenthetical phrase, i.e. removing the phrase changes the meaning of the sentences or creates a meaningless constructions. Example: "He has sometimes has difficulty reading the screen, for example when his eyes get tired."
  • To delimit a "non-restrictive relative clause" (a type of clause that you can leave out without changing the meaning of the main clause):
    • "The tests, which will take only half an hour, will take place in the usability lab."
    • "This document is available under Creative Commons, which is a licence for content, not software."
  • After an introductory phrase:
    • "The son of a shoe maker, he gained a place at King’s School Canterbury from where he won a Parker scholarship to Corpus Christi College, Cambridge." (Introductory appositive phrase; source: University of Cambridge - CC BY-NC-SA 3.0)
    • "The result of eight years of research, this book is jam-packed with …" (Introductory appositive phrase; source.)
    • "W3C has published the January 2015 edition of Standards for Web Applications on Mobile, (…). A deliverable of the HTML5Apps project, this edition includes changes and additions since October 2014, and covers continued progress of the platform." (Introductory appositive phrase; source: W3C weekly newsletter.)
    • For more examples of introductory phrases, see "Commas After Introductions" in Purdue University's Online Writing Lab.

Notes:

  • Note the difference in meaning between, "I saw a film which was very boring" and "I saw a film, which was very boring". The first sentence implies that the film I saw was very boring, while the second implies that watching films was a boring activity. In the first sentence, "which" can be replaced with "that"; this is not possible in the second sentence. In speech, there would be a pause before "which" in the second sentence, but not in the first sentence. Grammatically speaking, the first sentence contains a "restrictive relative clause" (the which clause restrict the meaning of "film" to one particular film), while the second sentence contains a "non-restrictive relative clause" (the which clause just provides some additional information but the main clause does not change in meaning without the which clause).
  • You do not write a comma to introduce a "restrictive relative clause", i.e. a clause that is necessary to identify the person or thing you are talking about. E.g.:
    • The man who can dominate a London dinner-table can dominate the world. (Oscar Wilde)
    • The man who doesn't read good books has no advantage over the man who can't read them. (Mark Twain)

Semicolon

Outside programming, the semicolon is mainly used in two situations.

  1. To join two complete sentences without a connecting word such as and or but and when the colon is not a valid alternative. Example:
    • Some matchmakers are already implemented and integrated into the Cloud4all Personalisation framework; other matchmakers will be implemented in the next project years. (Quoted from Cloud4all deliverable D204.1.)
  2. To separate items in a list that already contain commas. Example:
    • The people present were Jamie, who came from New Zealand; John, the milkman's son; and George, a gaunt kind of man. (Quoted from Wikipedia: Semicolon.)

Some other good examples are available in Larry Trask's Guide to Punctuation.

Colon

The colon is used to illustrate, explain or elaborate the preceding sentence.

Examples:

  • Code contributed to GPII should be made available under one of the following licences: the Apache License 2.0, the BSD 3-Clause License or the MIT License.
  • To install an extension in OpenOffice, proceed as follows: open the Extension Manager in the Tools menu, click "Add...", browse to the folder where you downloaded the extension, click "Open" and follow the instructions that appear during the installation process.
  • The presentation is available in two formats: ODF and PDF.
  • I had a rough weekend: I had chest pain and spent all Saturday and Sunday in the Emergency room. (Quoted from Wikipedia: Colon.)

The colon is also used to introduce a longer quotation that is marked off from the rest of the text by indentation. Example:

As Samuel Johnson wrote:
  Every man naturally persuades himself that he can keep his resolutions, 
  nor is he convinced of his imbecility but by length of time and frequency of experiment.

Some other good examples are available in Larry Trask's Guide to Punctuation.

Long Dash

The hyphen (-) is not the appropriate punctuation mark for parenthetical remarks; use the long dash (—) instead.

Two successive hyphens do not replace a long dash, though some word processors may automatically replace the double hyphen with a long dash. (The double hyphen was a workaround on mechanical typewriters, which did not have a longdash.)

Quotation Marks

TODO

Common Grammar Problems

That, Which or Zero Relative Pronoun

That and which are relative pronouns, i.e. words that introduce a relative clause. A relative clause is a type of subclause that provides additional information about a word or phrase (the "antecedent") in the main clause. For example, in the sentence "The house that Jack built was large":

  • "The house was large" constitutes the main clause;
  • "that jack built" is a relative clause;
  • "The house" is the antecedent;
  • "that" is the relative pronoun that refers back to the antecedent ("the house").

Examples with that (with the subclause in italics):

  • "that" is the subject of the subclause, so it cannot be omitted.
    • The paper that won the award was highly influential in creating a new field of research.
  • "that" is the object of the subclause, so it may be omitted.
    • The paper (that) he presented at the HCI conference describes a new usability evaluation method.
  • "that" is the object of a preposition ("to") in the subclause and is usually omitted.
    • The research (that) she referred to was new to me.
  • "that" can be used to introduce a clause following a superlative, "the only", "all" etc:
    • Who was the greatest scientist that ever lived?
    • This is the only paper that provides a literature review of resistance to technology adoption by people with disabilities.
  • "that" can be used instead of "when" after an expression of time:
    • By the time that/when the project ended, the software had been downloaded 25,000 times.

Examples with which

TODO

Note: The choice between "that" and "which" is sometimes a matter of dispute.

Use of Tenses

This section covers only a few basics. For more details, you should consult one of the grammar listed at the end of this page.

Present

The present progressive indicates action that is taking place at the moment of speaking. The form is: be [conjugated] + verb + -ing.

  • John is attending a teleconference. Please don't disturb him now.


The present simple (or simple present) refers to

  • actions or events that are generally true or habitual. The action or event does not necessarily take place at the moment of speaking.
  • actions in a theoretical sequence of events.
  • actions that depend on another action.

Form: verb [conjugated], i.e. the bare infinitive (without "to"), marked for person and number. Form in questions: do [conjugated] + verb [infinitive].

  • John develops software. (He does this for a living.)
  • At sea level, water boils at 100°C.
  • The sun always rises in the east and sets in the west.
    • Question: Why does the sun always rise in the east and set in the west?
  • The user launches the PMT and creates a preference set. The system provides a token and the user saves the token to a USB key.
  • I will respond as soon as I receive your e-mail.

Past

The past progressive refers to

  • action that was ongoing in the past and serves as a background for another event or action;
  • action that took place in the past in is viewed as an ongoing situation.

Form: be [past tense] + verb + -ing.

  • The cat ate my homework while I was sleeping.
  • At three o'clock yesterday, I was attending a teleconference.
  • I was writing an e-mail when I received his phone call.


The past simple (or simple past) refers to

  • action that took place before the current moment and that has no connection with the current time;
  • habitual actions or events in the past.

Form: verb + -ed (except for irregular verbs: went, wrote, ran, made, did, ...). In questions: do [conjugated] + verb [infinitive].

  • We submitted the deliverable last week.
    • Question: When did you submit that deliverable?
  • I wrote 20 e-mails this morning. (=Said when the morning is over.)
  • Last week, it rained every day.


The present perfect refers to an action that took place before the moment of speaking and that has a result that affects the current situation or that took place in a time frame that extends to the present time. Form: have + past participle.

  • I have written 20 e-mails this morning. (It is still morning, so it is possible to write a few more before noon.)
  • I have eaten. (Implies that the speaker is no longer hungry.)
  • I have lived in Germany for two years / since 2012. (Implies that the speaker still lives there.)

Future

The future progressive is mainly used to refer to an action or event that will be in progress at a particular point in the future. Form: will be + verb + -ing.

  • I will be attending a conference call at 3 p.m. tomorrow.


The future simple (or simple future) is mainly used to refer to * an action or event that will take place after the current moment and that has no real connection with the current time;

  • a future action or event that depends on some condition.

Form: will + verb.

  • The test facilitator will ask the individual if he or she wishes to be anonymous.
  • The next face-to-face meeting will be held in November.
  • I will review the deliverable if I can.

Notes:

  • Never use the future simple in an adverbial clause of time or condition (e.g. introduced by "if ...", "when ...", "after ...", etc.) even though the event might be in the future. Instead, use the present simple in the subclause.
    • Americans will understand you perfectly well if you use 'got' instead of 'gotten'.
    • He will come home when he wants to.
  • "will" also has other uses, for example:
    • You will submit your paper through the conference management system. (order)
    • I will submit the paper on time. (promise)
    • You will not go there. (negative order, refusal)

Split Infinitives

It is a myth that you cannot use a split infinitive, e.g. "To boldly go where no man has gone before". The split infinitive already existed in Middle English.

Examples from deliverables:

  • "to organize better the walks" -> "to better organize the walks" (in this case, the split infinitive improves the sentence)

Articles (a, the)

English has two articles: "the" (definite article) and "a/an" (indefinite article). The choice between the definite article, the indefinite article or no article depends on several things. Below are a few basic rules.

"The" is used in the following situations:

  • before nouns that refer to something that is identifiable to the reader:
    • The project started in 2012. (We assume that the reader knows which project, e.g. because it has been mentioned before.)
    • The version we will user for testing is not ready yet. (The phrase "we will use for testing" makes the version identifiable.)
  • before nouns that refer to something unique:
    • The Moon is the only natural satellite of the Earth.
  • before an adjective to refer to all members of a class or nationality:
    • The expression "squaring the circle" is sometimes used as a metaphor for trying to do the impossible.
    • The French are often perceived as taking a great pride in national identity.

"A/An" is used in the following situations:

  • before nouns that refer to something that is not identifiable to the reader:
    • Updating a screen reader can cost hundreds of euros.
  • before nouns that refer to any member of a group:
    • A screen reader is a software application that attempts to identify and interpret what is being displayed on the screen. (Or: Screen readers are software applications that ...)
    • node-inspector requires a WebKit-based browser. (Any browser based on WebKit.)

No article (or the "zero article") is used in the following situations:

  • with generic nouns:
    • Accessibility is hard. (Generic mass noun. Compare "The accessibility of OpenOffice has improved a lot", which is specific.)
    • Screen readers are a form of assistive technology (AT) potentially useful to people who are blind, visually impaired, illiterate or learning disabled. (Generic plural noun.)
    • He designs and develops websites. (Indefinite plural noun.)
    • I drink tea. (Indefinite mass noun.)
  • The experimenter does not have information about the state of the box contents. (Or "The experimenter does not have any information about ...")
    • There are lies, there are outrageous lies, and there are statistics. (Quoted on Wikipedia.)
  • with many proper names: John, Spain, Lisbon etc.

Prepositions

Examples:

  • "different from" (not "... to")
  • "independent of" (not "... from")
  • "used by" (not "... from")
  • "apply something to something" (not at): e.g. "the settings are applied to the interface"

Apostrophes, Possessives and Contractions

Project deliverables, journal articles and other forms of formal writing should avoid contractions such as "can't", "isn't", "it's, etcetera. Instead, write "cannot", "is not", "it is", respectively.

Possessive forms are usually written with an apostrophe followed by an 's' ('s:

  • after names: "Douglas Crockford's new book"
  • after nouns etc.: "the participant's name", "this year's review", "everybody's acceptance tests", ...

There are a few special cases:

  • names ending in an 's' that is pronounced: possessive form with 's: "James's car"
  • names ending in an 's' that is non pronounced: possessive form with only an apostrophe: "Socrates' maeiutics"
  • plural nouns: possessive form with only an apostrophe: "both users' preferences", "two days' work"

The following phrases have different meanings:

  • "the user's participation" (the participation of one specific user) versus "the users' participation" (the participation of several users).
  • "its" is a possessive pronoun (like "his" and "their") while "it's" is a contraction of "it is".

For more details about possessives, see Larry Trask's Guide to Punctuation.

Singular They

Singular "they" is the use of "they" (and its inflected forms "them" and "their") to refer to a single person. It is typically used to avoid constructions such as "he/she", "him/her" and "his/her", i.e. as a gender-neutral pronoun.

Even though "singular they" refers to a single person, the verb should still be conjugated in its normal (i.e. plural) form. Examples:

  • The user said that they prefer high contrast.
  • When a user first sets up a preference set they can start by …
    • (Instead of: "When a user first sets up a preference set he/she can start by …".)
  • A manufacturer fills out their product descriptions one at a time before they submit …
    • (Instead of: "A manufacturer fills out his/her product descriptions one at a time before he/she submits …".)

Note: When referring to a person of known sex, it is advisable to use the singular pronoun. For example:

  • No mother should be forced to testify against her child.
  • John updates his preferences using the preferences editor.

Adjectives and Adverbs

In general, adverbs can be formed by adding -ly to adjectives.

Examples:

  • slow: to drive slowly.
  • incredible: incredibly boring.
  • "This is a kind reminder to fill in the Doodle poll." (adjective) versus "May I kindly remind you to fill in the Doodle poll?" (adverb).
  • "a brief presentation" (adjective) versus "briefly present the project" (adverb).

There are a few exceptions to the above adverb formation rule:

  • Some adjectives cannot be turned into adverbs by adding -ly, for example, big, fast. For example: "Drive fast, see our judge" (funny traffic sign).
  • Some adjectives cannot be turned into adverbs by adding -ly without a change of meaning.
    • The primary meaning of hardly is "scarcely, barely". (So the expression "I have hardly worked" has a different meaning than "I have worked very hard".)
    • The primary meaning of shortly is "soon". When you want to say something in a few words, you can use the adverb "briefly".

Syntax

Compound Sentences

TODO

Examples from deliverables:

  • "In particular, and before the accident, Jane as any other person of her age was an active social network member." -> "Before the accident, Jane was an active social network member, like any other person of her age."

Conjunctions versus -ing Forms

Too many sentences connect a main clause with a subclause by means of an -ing form. Conjunctions express these connections better.

Examples from deliverables:

  • "This is a very interesting application scenario, highlighting the need to address contextual aspects in the applicability of user N&Ps." -> "This is a ... scenario, because it highlights ..."


Sentence Length

Sentences are not sausages in which you can stuff as many words as you want. Non-native speakers of English can considerable improve their writing by creating shorter sentences.

Examples from deliverables:

  • "Joad is 68-year old and one of his hobbies is walking through the paths around the mountains nearby the city area where he lives." -> "Joad is 68 years old. One of his hobbies is ..."
  • "Although Lissa is using a computer keyboard and mouse, her mouse control skills are sometimes limited, making it hard for her to ..." -> "Although Lissa uses ..., her mouse control skills are sometimes limited. This makes it hard for her to ..."

Vocabulary

Confusable Words and Phrases

Some words in deliverables and papers have a different meaning than the author intended.

  • briefly versus shortly:
    • briefly means "In a brief manner, summarily" (e.g. "I will briefly describe the history of assistive technology.") and "For a brief period".
    • shortly means "In a short or brief time or manner; soon; quickly" (e.g. "Diaspora will shortly announce 100 million users." "The accident occurred shortly before noon.") or "In an irritable ("short") manner".
  • "what it looks like" = "how it looks"
    • Both expressions have the same meaning but are sometimes incorrectly merged into how it looks like.
  • needed versus necessary + to/for:
    • "X is needed to/for" means that X is wanted or required for a certain purpose or to reach a certain goal. "Needed to" introduces a verb or a verb phrase; "needed for" introduces a noun or a noun phrase. Examples:
      • "Perfetti & Landesman (2001) suggest that more than 8 testers are needed to detect all usability issues." (How many testers are enough?)
      • "More observed events would be needed in order to reduce the uncertainty surrounding the estimated effects of salt reduction." (Unclear results for salt reduction study)
      • "What is the approximate number of words needed in order to reach conversational fluency in a language?"
      • "Rolf Molich, in an article for UI 11 2006 Conference also states that “the number of users needed for web-testing depends on the goal of the test.”" (How many testers are enough?)
    • You cannot say "It is needed to (+ verb)", unless "It" refers to a noun phrase from the preceding sentence. If "it" does not refer to a preceding noun phrase, you should write e.g. "We need to (+ verb)", "The project needs to (+ verb)" or "It is necessary for us to (+ verb)" instead.
    • "X is necessary to/for" means that X is essential for a certain purpose (especially when something cannot be done without X); in some cases there may be a rule or authority that demands X. Examples:
      • "Universities tend to be flexible about which A-levels, A/S, GNVQ or Scottish Higher subjects are necessary for entry onto psychology degrees (...)" (Entry requirements for psychology)
      • "We arrange appropriate tests for you when they are necessary for diagnosis and care." (Test Results)
      • "No appointment is necessary for our daily open access sessions (...)" (Appointments)
    • "It is necessary for X to (+verb)" introduces an action that is essential or that cannot be avoided. Examples:

See also the list of confusable words by the University of Bristol.

Register and Bloated Language

Some words in deliverables and papers have a different connotation than the author intended. For example, some researchers use legal English when more readable alternatives exist:

  • hereinafter: "after this"
  • aforesaid (usage: "the aforesaid x") and aforementioned: "mentioned earlier", "referred to earlier" (usage: "the x mentioned earlier").

Some words in deliverables are chosen because they are longer, sound smarter or more "impressive" but make the text harder to read. For example:

Abbreviations

"e.g." versus "i.e.":

  • "e.g." means "for example" (if you provide a list of examples, it is not necessary to add "etc." at the end).
  • "i.e." means "that is" or "in other words" and is used to clarify something be restating it or explaining it more clearly.

Nominalisation

Nominalisation is the use of an adjective, verb or adverb as if it were a noun. For example: "You cannot change the user interface language" (verb) versus "There was no change" (noun).

Many languages allow the nominalisation of adjectives and past participles in order to refer to persons. For example, "deceased" can be used in the phrase "the deceased" (persons or persons who have recently died). However, which adjectives and past participles can be used in this way varies between languages, so you sometimes need alternative formulations when translating into English.

Examples:

  • "the person(s) in charge of ...", "leader", "person responsible for" instead of "the responsibles"

Nominalisations such as "the blind", "the poor" and "the unemployed" refer to a category of people and take a verb in the plural form. For example: "The blind have access to less than 5% of printed material in most parts of the world." ("The blinds" has a completely different meaning.)

British, American and Canadian Vocabulary

British, American, Canadian and other varieties of English don't always use the same word to the same concept. In addition, the same word can have different meanings in different English-speaking countries.

Examples:

  • Both caretaker (UK) and caregiver (US and Canada) can mean carer.

References

Online Style Guides and Writing Advice

British English:

American English:

Scientific & academic English:

Printed Style Guides and Writing Advice

Most of the advice given by American style guides also apply to prose in British English. The American and British style guides below are listed separately because of differences in vocabulary, spelling and grammar.

American English:

British English:

Scientific & academic English:

See also:

  • Rachael Cayley: "Key Sources", Explorations of Style, 2 February 2011. Recommends the following books: Jacques Barzun, Simple and Direct: A Rhetoric for Writers; Wayne C. Booth, Gregory G. Colomb and Joseph Williams, The Craft of Research; Claire Kehrwald Cook, Line by Line: How to Edit Your Own Writing; Gerald Graff and Cathy Birkenstein, “They Say/I Say”: The Moves that Matter in Persuasive Writing; Joseph M. Williams, Style: Toward Clarity and Grace.
  • Rachael Cayley: "“Can you recommend a good book on writing?”", Explorations of Style, 4 April 2013. Recommends the following books: Jacques Barzun, Simple and Direct: A Rhetoric for Writers; Howard S. Becker and Pamela Richards, Writing for Social Scientists: How to Start and Finish Your Thesis, Book, or Article; Wayne C. Booth, Gregory G. Colomb and Joseph Williams, The Craft of Research; Claire Kehrwald Cook, Line by Line: How to Edit Your Own Writing; Peter Elbow, Writing with Power: Techniques for Mastering the Writing Process; Gerald Graff and Cathy Birkenstein, “They Say/I Say”: The Moves that Matter in Persuasive Writing; Patricia T. O’Conner, Words Fail Me: What Everyone Who Writes Should Know About Writing; William Strunk, Jr. and E.B. White, The Elements of Style; John M. Swales and Christine B. Feak, Academic Writing for Graduate Students: Essential Tasks and Skills; Joseph M. Williams, Style: Toward Clarity and Grace.

Grammar

Online grammars:

  • The Internet Grammar of English (University College London. Also available as an app for Android and Apple iOS.)
  • Linguapress: English Grammar. (For people who learn English as a foreign language.)
  • Purdue Online Writing Lab: Grammar. (American English. For native speakers.)

The grammars below are suitable for learners of British English.

  • Geoffrey Leech, Jan Svartvik: A Communicative Grammar of English. 3rd edtion. Pearson, 2003.
  • Michael Swan: Practical English Usage. 3rd edition. Oxford University Press, 2004 (Organised as an A-Z dictionary of problem points. Covers mostly grammar, but also selected points of vocabulary, idioms, style, pronunciation, and spelling. Does not contain exercises.)
  • Raymond Murphy: English Grammar in Use. 4th edition. Cambridge University Press, 2012. (Contains many examples and exercises; the book is available in editions with and without solutions.)
  • Ronald Carter, Michael McCarth: Cambridge Grammar of English: A Comprehensive Guide. Cambridge University Press, 2006. (Very comprehensive; contains sections that highlight problem areas for language learners; contains a section on academic English; distinguishes between spoken and written English; appendices also cover punctuation and spelling.)

The grammars below are suitable for learners of American English.


Use of tenses or verb forms:

Use of articles:

  • The Writing Center, University of North Carolina at Chapel Hill: Articles: three basic rules for the use of articles, specifically written for non-native speakers of English. (Handout available under Creative Commons by-nc-nd 2.5.)
  • Purdue Online Writing Lab: Using Articles.

Vocabulary and Dictionaries

For non-native speakers of English, a "learner's dictionary" is more useful than a dictionary aimed at native speakers. When you choose a dictionary (whether printed or digital), check that it provides usage notes (e.g. on difference between certain synonyms and near synonyms, e.g. "change", "alter" and "modify"), full sentence examples and examples of prepositions that can be used with the noun or verb you are looking up.

Also useful:

  • The Academic Phrasebank by the University of Manchester helps you find examples of key words and phrases. Non-native speakers of English are one of the primary audiences of this resource.

Punctuation

Many of the resources listed above also cover punctuation.

British English:

American English:

Canadian English:

  • Rachael Cayley: "Dashes", 6 April 2011.
  • Rachael Cayley: "Interrupting Yourself", 20 April 2011. About the use of dashes, commas and parentheses to interrupt sentences with additional information.

International:

Links to Tips, Advice and Thoughts