Grammar

Abbreviations

Do not terminate abbreviations with a period if the last letter of the unabbreviated form is included in the abbreviation. For example:

Mr Smith
Mrs Smith
Ms Smith
Prof. Smith
Dr Smith
St Petersburg
Microsoft Corp.
M. Duval [abbreviation of the French word monsieur]

In general, plurals of abbreviations are formed by adding a lowercase s. Do not use apostrophe s (’s) for this purpose.
For example:

SOPs
[abbreviation for standard operating procedures; not SOP’s]

APIs
[Not API’s.]

Commonly known abbreviations are listed in .github/styles/Vaadin/Abbr.yml.

Adverb Phrases

If you begin a sentence with an adverb phrase, place a comma after the phrase.
For example:

Unfortunately, we cannot reproduce the bug.
As you can see, the screen layout is logical.
This morning, I spoke to our customer services manager.

Angle Brackets

In general text,the name for the < and > characters is angle brackets.
In other contexts, the same characters are known as the less than and greater than symbols.

Apostrophe (’)

The apostrophe has a specific function: to indicate when one or more letters have been omitted. For that reason, it is used in contracted forms of verbs.

In general, in our technical documentation, we avoid using contracted forms. They are correct English, but they are more appropriate to less formal writing.

Nevertheless, to show the function of the apostrophe in contractions in general, here are some examples:

I amI’m
[The letter a is omitted.]

She isShe’s
[The letter i is omitted.]

They are notThey aren’t
[The letter o is omitted.]

In some cases this logical system of contraction has been adapted, by convention and usage. For example:

He will notHe won’t
[A little illogical, but it is the accepted contraction.]

We shall notWe shan’t
[And not, for example, sha’n’t.]

The other standard use of the apostrophe in English is to indicate possession.

In fact, this has its logic. In Old English, the possessive case of a noun was formed by adding -es to it.

In modern English, the e has been dropped from that suffix; this omission is now marked by that apostrophe.

The possessive form of a single noun is formed by adding ’s. For example:

The developer’s guide

The boss’s office

The possessive of a plural is formed by the following process:

  • write the ordinary plural form

  • if that plural form already ends in s (the commonest case), place the apostrophe after that s

  • in the few irregular cases where the plural form does not end in s (for example, men, women, children, sheep), add ’s, as for a single noun

For example:

The employees’ salaries
The bosses’ salaries
The women’s records
The mice’s tails

For when to form a possessive using an apostrophe, and when to use of, see Possessive.

Apposition

Consider this sentence:

The CEO, Nick Smith, spoke to a company employee.

In this sentence, The CEO and Nick Smith identify the same entity (in this case, a person). In other words, Nick Smith is another name for the CEO.

In the terminology, the phrase Nick Smith is "in apposition" with the CEO.
Notice that the phrase that is in apposition is delimited by commas.

Now, consider this sentence:

The CEO, Nick Smith, spoke to company employee Susan Rae.

In this case, company employee and Susan Rae do not identify the same entity.
It is likely that there is only one Susan Rae in this context, but there are, no doubt, many company employees. In other words, Susan Rae is not another name for company employee.

Hence, Susan Rae is not in apposition with company employee and, for that reason, is not delimited by commas here.

Let’s look at an example that is more relevant to the context of technical documentation.
Here is some information about the parameters of a method.

The method takes a single parameter: duration.
The method’s parameter, duration, specifies the time in milliseconds that the animation should run.

Here, as there is only one parameter, the method’s parameter and duration refer to the same entity. Duration is in apposition with the method’s parameter, and so is delimited by commas.

Now, here is some similar information but, this time, the method takes more than one parameter.

The method takes two parameters: startTime and duration.

The parameter duration specifies the time in milliseconds that the animation should run.

Here, parameter and duration do not mean the same thing. For this reason, duration is not in apposition with parameters, so it is not delimited by commas.

Articles

Missing and misused articles (a, an, the) are a very common problem, especially for speakers of languages which do not have articles, such as Finnish, Russian, and Japanese.

Although the basic concept of articles is quite simple, there are some special cases and exceptions that can complicate the issue. You may find the following useful:

Conditional

Contractions

Contractions (or "contracted verb forms") are those where one or more letters are omitted. For example:

She’s on her way to the meeting. [She’s is a contraction of she is.]

They’ll be here on Friday. [They’ll is a contraction of they will.]

In general use, contractions are perfectly acceptable and correct. In fact, using contractions can help to make a non-native speaker’s English sound much more natural.

However, contractions are not generally appropriate in formal contexts, such as academic works and legal documents. We have made the decision not to use contractions in our technical documentation, perhaps sacrificing a little friendliness of tone in the interests of simplicity of language.

Countable and Uncountable Entities

Some entities have the characteristic of existing as separate objects, such that we can count them.
For example, books are objects that exist separately from each other, so that it makes sense to talk about one book, two books, and so on.
We call this category of objects countable.

We view some other entities as existing in bulk, as amounts of something, rather than a number of separate objects that we can count.
For example, we apply the label air to a contiguous body of gaseous substances. It does not usually make sense to talk about one air or two airs.
The same applies to entities such as sugar, water and aluminum.
We call this category of entities uncountable.

From the point of view of grammar, it is important to consider whether or not some entity is countable.
For example, the indefinite articles, a and an, convey the meaning of one of something.
Hence, it makes sense to use them with countable nouns, but not with uncountable ones.
The phrases an air or a water have no meaning.

Similarly, countable nouns, by definition, can be plural.
Uncountable nouns, again by definition, cannot be plural.

However, there is a small trap here.
Many nouns cannot be categorically defined as either countable or uncountable; it depends on their meaning in the given context.

For example, time as a concept is uncountable.
It would not make sense to say, for example:

I’m sorry I haven’t got a time to talk to you now.

On the other hand, time is countable when it means an occasion or a period.
For example:

I remember a time when 1 MB was a lot of memory.
How many times have I asked you not to do that?

Consider, too, the difference between:

I don’t like coffee.
and
Would you like a coffee?
How many coffees have you had this morning?

Dangling Participles

Participles are formed from verbs.

Present participles end in -ing; past participles often end in -ed, though there are many irregular forms. Some examples:

infinitive

present participle

past participle

to bring

bringing

brought

to have

having

had

to lead

leading

led

to walk

walking

walked

to write

writing

written

Participles are often used as convenient concise forms. For example:

Being the project leader, Hannah Jones chaired the meeting. [A more concise form of: As she is the project leader, Hannah Jones chaired the meeting.]

I was given a spec written on the back of an envelope. [An alternative form of: I was given a spec that was written on the back of an envelope.]

Having caught a terrible cold, I phoned my colleagues to postpone the meeting. [In other words: As I had caught a terrible cold, I postponed the meeting.]

Participles can work well when used in this way, but we need to be careful that our sentence is unambiguous. Consider the last example again:

Having caught a terrible cold, I phoned my colleagues to postpone the meeting.

Who had caught the cold? Was it me or was it my colleagues? Clearly, it was me, but how do we know this? We know because we assume that the next noun phrase after the participle clause indicates the person or thing that the participle refers to.

Look at these similar sentences:

Being corrupt, the file was rejected. [Since the next noun phrase after the participle phrase is the file, it is clear that it is the file that is corrupt.]

Being corrupt, I rejected the file. [In this case, basing our understanding purely on the word order, we might interpret this to mean that I am the one who is corrupt.]

In most cases of such poorly chosen word order, we can probably guess at the intended meaning. However, our goal is that our readers should correctly interpret our material on the first reading.

When the structure of the sentence leaves it unclear to whom or what the participle refers, this is called a "dangling" or "unrelated" participle.

Here are some other examples of poorly chosen, and hence distracting, word order, with some suggestions for improvement:

"Dangling participle" version

Improved version

Being a public holiday, the office was closed.

As it was a public holiday, the office was closed.

Having crashed three times in one week, we decided to replace the server.

As the server had crashed three times in one week, we decided to replace it.

Definite Article (“the”)

Indefinite Article

Introduction

Nouns as Descriptors

English is very versatile in allowing nouns to be used as if they were adjectives. For example:

Please close the office door quietly.

Select your preferred keyboard layout.

Bear in mind that when nouns are used like adjectives in this way, they are almost always used in the singular form, not plural. For example:

She is the manager of a shoe shop. [Not a shoes shop.]

This is the responsibility of the microchip manufacturer. [Not the microchips manufacturer.]

Passive Voice

Grammatically speaking, there are two kinds of voice: active voice and passive voice.

An active sentence generally follows the standard subject – verb – object format.
For example:

The dog bit the man.

In an active sentence such as this, the subject of the verb (the dog) is also the agent (the person or thing that performs the verb).

On the other hand, in a passive sentence, the subject of the verb is not the agent; that is, it is not the person or thing that performs the verb.

The man was bitten by the dog.

In this sentence, the subject of the verb is now the man; but the agent is still the dog.
In a passive sentence, the agent is indicated using the preposition by.
Specifying the agent is grammatically optional; that is, we may choose not to do it.
For example:

The man was bitten.

We use the passive voice for three common reasons:

  • to place emphasis on a different part of the sentence

  • because we do not know who or what the agent is

  • because it is unimportant who or what the agent is.

The passive voice is often useful and appropriate.
For example:

English is spoken all over the world.

To express this as an active sentence, we would have to say

They (or 'people') speak English all over the world.

Unfortunately, this may lead us to wonder who they (or people) are, even though in this case it is unimportant.
For this reason, the passive version is preferable here.

However, in terms of style, using the passive too much can have the effect of making our language sound excessively formal.

Accordingly, avoid using the passive when it is possible to express the same idea elegantly and simply in active voice.

Phrasal Verbs

Relative Clauses

Relative clauses allow us to give more information about a person or thing that we mention in a sentence. For example:

Instead of saying: I asked Linda Johnson. She works in the same office as me,

it is neater to say: I asked Linda Johnson, who works in the same office as me.

They are called "relative clauses" because they relate to some entity in the main clause of our sentence. The word that links the relative clause to the main clause is often a "W" word, such as which, who, where, when, or whose. The word that is also often used as the linking word. For example:

The software is written in Java, which is our preferred language.

Jean Reboulet, who led the design team, attended the meeting.

The conference was held in San Francisco, where the company has its headquarters.

We recommend performing full backups at the weekend, when the system is less busy.

We contacted Sandra Stein, whose team maintains the library.

This is the team that maintains the library.

We need to be aware that there are two kinds of relative clause: defining and non-defining.

Why is this important? It matters because it has an impact on the punctuation we need to use, and also on the sentence structure.

A defining relative clause, as the name suggests, defines an entity in the main clause. It gives us essential information in order to identify the person or thing that was mentioned. In other words, without the information in this clause, our sentence would not have the same meaning and might not even make sense at all. For example:

This is the bug which our testing team reported.
[The relative clause is essential in order to understand which bug is being talked about.]

The place where you parked your car is private property.
[The relative clause identifies the place that was mentioned.]

Split Infinitive

The infinitive of a verb is the form that includes the particle "to". Examples of infinitives are to have, to hold, and to program.

Traditionally, it was considered bad style to "split" the infinitive by placing an adverb between the particle and the verb. For example:

It is necessary to fully understand the process before starting. [Instead of, for example, to understand the process fully.]

We had to completely rebuild the library. [Instead of, for example, to rebuild the library completely.]

Although split infinitives are generally considered to be acceptable these days, it is worth considering whether you could easily write your sentence so as to avoid it.

However, there may be some cases where strictly imposing the ideal of avoiding split infinitives could result in an awkward sentence or even introduce ambiguity. Clearly, we need to prioritise simplicity, clarity, and accuracy at all times, even if it means we have to compromise on elegance.

Time Clauses in the Future

We often use time clauses to refer to some time in the future. Such clauses may begin with when, while, until, as soon as, before, and after. In English, we generally use a present or present perfect tense in this type of clause, in spite of the fact that it refers to a future time. The remainder of the sentence may use any appropriate future form, or an imperative (instruction) form. For example:

As soon as you get to the office, call me. [Not As soon as you will get…]

While I am in Scotland, I’ll visit Edinburgh Castle. [Not While I will be in Scotland…]

When you have finished that work, you can start the next task. [Not When you will finish… or When you will have finished…]