Grammar

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

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

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

See also Latin Abbreviations.

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

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.

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

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

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

The other standard use of the apostrophe in English is to signify 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 possessive of a plural is formed by the following process:

For example:

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

Consider this sentence:

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’s in apposition is delimited by commas.

Now, consider this sentence:

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

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

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

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.

Here, parameter and duration don’t mean the same thing. For this reason, duration isn’t in apposition with parameters, so it’s not delimited by commas.

Missing and misused articles (a, an, the) are a very common problem, especially for speakers of languages which don’t 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:

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

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 aren’t generally appropriate in formal contexts, such as academic works and legal documents.

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 many separate objects that we can count.
For example, we apply the label air to a contiguous body of gaseous substances. It doesn’t 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’s important to consider whether 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, can’t be plural.

However, there is a small trap here.
Many nouns can’t 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:

However, time is countable when it means an occasion or a period.
For example:

Consider, too, the difference between:

Participles are formed from verbs.

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

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

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:

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 denotes the person or thing that the participle refers to.

Look at these similar sentences:

Usually with 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:

See "a" / "an"

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

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:

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:

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).

By contrast, in a passive sentence, the subject of the verb is not the agent; that is, it isn’t the person or thing that performs the verb.

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 denoted using the preposition by.
Specifying the agent is grammatically optional; that is, we may choose not to do it.
For example:

We use the passive voice for three common reasons:

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

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

Unfortunately, this may lead us to wonder who they (or people) are, even though in this case it’s 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’s possible to express the same idea elegantly and simply in active voice.

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

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:

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 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:

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:

Although split infinitives are generally considered to be acceptable these days, it’s worth considering whether you could easily write your sentence 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 prioritize simplicity, clarity, and accuracy always, even if it means we have to compromise on elegance.

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, although it refers to a future time. The rest of the sentence may use any appropriate future form, or an imperative (instruction) form. For example:

8BD95586-0E8D-4D5A-99B9-583629D4750D