Grammar
Introduction
This chapter caters to both English and Chinese speakers, bridging essential grammar concepts with writing strategies for technical documentation in both languages. Practical tips provided here will enhance your understanding of subsequent chapters.
Key topics include:
Parts of speech such as nouns, verbs, adjectives, and adverbs.
Effective use of articles, prepositions, and conjunctions for clarity.
Precise and inclusive pronoun usage.
Nouns
Use Concrete Nouns
Nouns can be categorized as concrete or abstract. Concrete nouns denote tangible entities like people, places, or objects, while abstract nouns represent intangible concepts. Since abstract nouns are harder to grasp, prioritize using concrete nouns to enhance readability.
Example
Preferred |
Avoid |
|---|---|
After that, the function bootloader_flash_unlock will be linked. |
After that, your implementation of bootloader_flash_unlock will be linked. |
In the example above, readability is improved by replacing the abstract noun implementation with the concrete noun function.
Pronouns
Address the User as You
Using the second person in documentation makes it more engaging and user-friendly. Its advantages include:
Creating a direct and approachable tone by addressing users as you.
Simplifying instructions with the imperative mood and active voice, reducing wordiness and clarifying the subject of actions in procedural steps.
Avoiding gender-specific third-person pronouns (he, she, his, hers). If third person is necessary, use they and their while ensuring proper noun-pronoun agreement.
Example
Preferred |
Avoid |
|---|---|
You can permanently switch the internal USB PHY to work with USB OTG peripheral. |
Users can permanently switch the internal USB PHY to work with USB OTG peripheral. |
In Chinese, use “你” instead of “您”.
Use First Person Pronouns (We, Our, I) Judiciously
First person plural pronouns such as we and our, focus on the writer or company (e.g., Espressif) rather than the user. Before using them, consider whether the second person or the imperative mood would create a more user-friendly experience. However, we can be used when appropriate and necessary for clarity.
Example
Preferred |
Avoid |
|---|---|
For production environments, we recommend generating the key pair using OpenSSL or another industry-standard encryption program. |
For production environments, it is recommended to generate the key pair using OpenSSL or another industry-standard encryption program. |
The first-person singular pronoun I is acceptable in the question part of FAQs.
Example
How do I specify the TLS protocol version for ESP32 AT?
Avoid Misleading Third Person 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 whether 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. |
Avoid using it as an empty subject wherever possible. Instead, use specific subjects to eliminate guesswork for the reader.
Example
Preferred |
Avoid |
|---|---|
Setting the Wi-Fi mode is necessary before connecting to a network. |
It is necessary to set the Wi-Fi mode before connecting to a network. |
Removing the dummy subject “It” renders a shorter sentence and allows your reader to grasp your meaning more quickly.
Here are some guidelines for effective pronoun usage:
Introduce the noun before using its pronoun to ensure clarity.
Position pronouns close to their referring nouns. If more than five words separate them, repeat the noun instead of using a pronoun.
Avoid confusion by reusing the noun if another noun is introduced between the original noun and its pronoun.
Verbs
Subject-Verb Agreement
Verbs have singular and plural forms. Use the verb form that agrees with the subject of the sentence in number.
Example
When the subject is |
The verb is |
Examples |
|---|---|---|
A group of things |
Singular |
A variety of flexible address filtering modes is supported by MAC Layer. |
Two or more singular things connected by and |
Plural |
After the receive module receives the packets, the Preamble and SFD of the received frames are removed. |
Two or more singular things connected by or |
Singular |
A reception or transmission of data is controlled by bit SPI_USR_MOSI or SPI_USR_MISO in SPI_USER_REG. |
A singular thing and a plural thing connected by or |
Singular or plural, to match the closest subject |
|
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. |
Use Strong Verbs
To engage and educate readers, choose strong and specific verbs. Reduce imprecise, weak, or generic verbs, such as the following:
Forms of be: is, are, am, was, were, etc.
Occur
Happen
Cause
Perform
A form of be is sometimes the best choice of verb, so don’t feel that you have to eliminate every form of be from your writing.
However, note that generic verbs often signal other ailments, such as:
An imprecise or missing actor in a sentence
A passive voice sentence
Preferred |
Avoid |
|---|---|
Dividing by zero raises the exception. |
The exception occurs when dividing by zero. |
The system generates this error message when… |
This error message happens when… |
We carefully ensure… |
We are very careful to ensure… |
When a variable declaration doesn’t specify a datatype, the compiler generates an error message. |
When a variable declaration doesn’t have a datatype, a compiler error happens. |
The submodule RAM functions as a buffer for sending and receiving data. It splits into two units: one handles sending data, while the other handles receiving data. The CPU and DMA control the sending and receiving processes by reading and writing data. |
The submodule RAM is a buffer area for sending and receiving data. It can be divided into two units: the one is for sending data, and the other is for receiving data. The process of sending and receiving data can also be achieved by the CPU and DMA for reading and writing. |
Typical Verb-object Collocations
Use verb-object collocations that adhere to clarity in technical documentation. Typical collocations include:
Example
Reset the chip
Power up the device
Flash firmware onto a device
Erase flash memory
Write data to flash
Read data from flash
Encrypt firmware before flashing
Establish connection
Configure Wi-Fi settings
Network a device
Go into sleep mode
Enter Mesh mode
Trigger an interrupt
Allocate memory
Access shared memory
Adjectives and Adverbs
Adjectives modify nouns.
Example
a unique data buffer
Adverbs modify verbs, adjectives or other adverbs.
Example
Watchdog timers must be periodically fed (reset) to prevent a timeout.
The adverb “periodically” modifies the verb “fed”.
Limit the use of vague adjectives and adverbs in technical writing, as they can be overly subjective and may resemble marketing language. Instead, prioritize objective, measurable details to enhance clarity and credibility.
Example
Preferred |
Avoid |
|---|---|
The timer module operates with an efficiency of over 95% and provides timing precision down to 1 microsecond. It supports frequencies of up to 80 MHz, making it suitable for time-critical tasks. |
The timer module is highly efficient and offers extremely precise timing for various applications. It can operate at a very high frequency, making it suitable for critical tasks. |
By reducing ferocious adjectives and adverbs, the description of the timer module gains more accuracy and credibility.
Prepositions
Prepositions link information about the time, location, or logical relationship of one noun to another word in a given sentence. Importantly, they tell us things like when or where one thing is among other things.
The table below demonstrates the typical uses of prepositions in technical documentation.
Preferred |
Avoid |
|---|---|
Flash reads and writes in STR mode. |
Flash reads and writes under STR mode. |
A field of B register |
A field in B register |
Conjunctions and Transitions
Conjunctions connect phrases or nouns within a sentence; transitions connect sentences themselves.
The most important conjunctions are as follows:
And
But
Or
When combining two words, phrases, or independent clauses with close logical connections, use a comma followed by a FANBOYS conjunction (for, and, nor, but, or, yet, so) or separate them with a period.
Example
Correct |
Incorrect |
|---|---|
ESP-IDF has all the code required to produce SystemView-compatible traces, so users can configure necessary project options. |
ESP-IDF has all the code required to produce SystemView-compatible traces, users can configure necessary project options. |
The most important transitions in technical writing are as follows:
However
Therefore
For example
Example
Correct |
Incorrect |
|---|---|
PeriBus1 features speculative read, which means it cannot guarantee that each read is valid. Therefore, the CPU has to use PeriBus2 to access some special registers, for example, FIFO registers. |
PeriBus1 features speculative read, which means it cannot guarantee that each read is valid, therefore, the CPU has to use PeriBus2 to access some special registers, for example, FIFO registers. |
In the example above, Therefore is an adverb, not a conjunction, so there should be a period or a comma plus a conjunction before. Note that the first sentence is already long, so we use a period, instead of adding a conjunction in the revised version.
Indefinite Article (A/An)
Indefinite articles (a and an) are adjectives used before a noun if the noun’s identity is unknown. Use of a and an implies that you’re not referring to a specific noun.
When you say or 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 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 |
n HDD |
An eɪtʃ - diː - diː |
Definite Article (The)
Definite Article Before Common Nouns
The definite article is used before a singular or plural noun when the noun is specific.
Use the in the following cases:
With something already mentioned.
When you define a specific object.
Example
The SHA Accelerator can only accept one message block at a time. Software divides the message into blocks according to “5.2 Parsing the Message”.
In the above example, “The SHA Accelerator” in the beginning refers to a specific device. It mentions “accept one message” and then use “divides the message” to make a specific reference.
With ordinal numbers and superlatives.
Example
Please always refer to the latest version.
For nouns with qualification (defined or specified by additional information).
Example
The memory region for storing configuration data must be accessed in 32-bit words.
In this example, “The memory region” refers to a specific memory region that is identified by its function, which is storing configuration data.
Definite Articles Before Proper Nouns
Software development platforms, hosting services, and search engines are proper nouns and do not require the definite article. These names, like “Beijing” or “China”, are always capitalized and used without “the”.
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
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.