English Grammar Tips

This chapter touches upon some aspects of English grammar and aims to help you avoid the most frequent mistakes.

The Indefinite Article (A/An)

Although the incorrect choice between the two forms of the indefinite article (a and an) occurs frequently, the good news is that this issue can be easily eradicated.

There is a ubiquitous misconception that the choice depends on the letter that follows the indefinite article. In reality, the choice depends on the sound that comes after the indefinite article!

When you say/write a word that starts with a consonant or a vowel with a consonant sound (e.g., u, eu, o as in one), you should use the a form of the indefinite article. However, if the first sound of a word is a vowel or a mute h, use an instead.

Most of the time, picking the right form of article is not hard.

Example

Initial Consonant Sound	Initial Vowel Sound
a board	an application
a network	an example
a status	an interface

However, sometimes you should be cautious when picking the right form of the indefinite article.

Example

Initial Consonant Sound	Initial Vowel Sound
a hard drive	an hourglass cursor [our-glass]
a one-pass compiler [wʌn - pass]	an online service
a user [ˈjuːzə(r)]	an update

Another tricky area is the use of abbreviations. The choice between the two forms of the indefinite article depends on how you pronounce the abbreviation.

The table below shows some examples of abbreviations whose pronunciation starts with a consonant.

Example

A + Abbreviation	Pronunciation
A CPU	A siː - piː - juː
A PSRAM	A piː - ɛs -ram
A PCB	A piː -siː- biː
A USB port	A juː- ɛs - biː port
A UART interface	A juː-ɑː(r)t interface

The following table provides examples of abbreviations with a vowel-sounding initial.

Example

An + Abbreviation	Pronunciation
An IoT solution	An ʌɪ-əʊ-tiː solution
An RToS	An ɑː(r)- tiː- əʊ- ɛs
An MDF device	An ɛm - diː - ɛf device
An XML file	An ɛks - ɛm - ɛl file
An HDD	An eɪtʃ - diː - diː

Those who want to experientially understand why n is sometimes added to the indefinite article should do the following exercise. Try saying “an application” and then “a application”. Most likely, you will find the pronunciation of the first option more natural and effortless. The reason is simple: n functions as a liaison giving your tongue a brief support between the two a sounds.

On the Usage of the Future Tense

In general, procedures and tasks described in technical documents develop in time continuously. They often tend to be repetitive or even have a pre-programmed nature.

This means that when you describe procedures and tasks, the present tense should work in most cases.

Example

Preferred	Avoid
Upon receiving this event, the event task initializes the lwIP network interface.	Upon receiving this event, the event task will initialize the LwIP network interface.
Here is an example of a random RADIUS client. It uses the password 12345678 to access `hostapd.radius_clients`.	Here is an example of a random RADIUS client. It will use the password 12345678 to access `hostapd.radius_clients`.

However, you can add some anticipation by using the future tense to emphasize the following:

The future result of the reader’s current action
What should follow if some certain conditions are satisfied or not satisfied

Example

Run the command printenv MDF_PATH. If the MDF_PATH environment variable has been set correctly, the command will return the path to the ESP-MDF project directory.

Misleading Pronouns

Personal pronouns in the third person, such as it (in the singular number) or them (in the plural number), can be confusing when the words they refer to are not immediately obvious.

In the example below, it is not obvious if the personal pronoun it refers to change rate, or touch reading.

Example

Correct	Incorrect
You need to reset the change rate of a touch reading for each channel and write the change rate into the file.	You need to reset the change rate of a touch reading for each channel and write it into the file.

The following example shows an issue with the pronoun them.

Example

Correct	Incorrect
Since the submodules on GitHub are represented as links to other repositories, this command is needed to download the actual files onto your PC.	Since the submodules on GitHub are represented as links to other repositories, this command is needed to get them onto your PC.

Them can refer to submodules as well as to repositories. Of course, you can grasp the meaning from the context, but the clarity of the sentence will significantly improve if you rewrite it. As submodules represent a set of files, you can use the synonymous phrase the actual files instead of repeating the same words.

Another suggestion is to avoid using it as an empty subject wherever possible.

Example

Preferred	Avoid
If `espwifisetmode` returns `ESPERRWIFINOTINIT`, then the Wi-Fi driver is not initialized by `espwifi_init` successfully.	If `espwifisetmode` returns `ESPERRWIFINOTINIT`, it means that the Wi-Fi driver is not initialized by `espwifi_init` successfully.

Another example shows how a conditional sentence with it as an empty subject can be elegantly turned into a simple sentence.

Example

Preferred	Avoid
The channel field of `wifiscanconfig_t` set to 0 indicates an all-channel scan mode.	If the channel field of `wifiscanconfig_t` is set to 0, it is an all-channel scan.

Avoid Using Contractions

Avoid using contractions in technical documentation, such as here’s, you’ve, can’t, don’t, it’s.

Please use full words instead.

Definite Articles Before Proper Nouns

The names of software development platforms, hosting services, and search engines do not require the definite article before them. These nouns actually belong to the category of proper nouns — names of particular people, places, companies, services, things, that are always capitalized and are never accompanied by the definite article, e.g., Beijing, China, etc.

Example

Correct	Incorrect
This method is useful if you have a slow connection to GitHub.	This method is useful if you have a slow connection to the GitHub.

Note

There are some exceptions with regard to capitalization:

Some proper nouns can be capitalized in a different way, like iPhone, which is the decision of Apple Inc.
Some proper nouns have the definite article accompanying them, like the Hague, The New York Times. In this case, the definite article is either the part of the name, or there are some historical reasons behind its retention.

However, if a proper noun is a modifier to the following noun, the presence of the definite article is necessary.

Example

Correct	Incorrect
Connect the ESP32 board to a PC.	Connect ESP32 board to a PC.

Here, the proper noun ESP32 requires the definite article, as it functions as a modifier (or an adjective) specifying which particular board is to be connected to the PC in question.

Correct example

The maximum throughput of Bluetooth LE communication between ESP32 boards can reach up to 700 Kbps.

In this case, the proper noun ESP32 does not take the, as it represents a set of objects (ESP32 boards), without referring to one specific board. As in the previous example, the proper noun ESP32 functions as an adjectival noun. The difference, however, is that in the previous example “the ESP32” referred to one specific board that was going to be connected to a PC; hence, the use of the definite article in that case.

On the Number of Verbs

The number of a verb must agree with the number of the noun or pronoun used with it. Pay attention to special nouns that can be either singular or plural. When choosing the number of verbs for such nouns, follow the usage conventions of the word and also take into consideration the specific context.

Note that the word “data” is preferred to be used as a singular noun.

Example

Preferred	Avoid
All the data is written and read via CPU directly.	All the data are written and read via CPU directly.

Provide feedback about this document