General Conventions
We would like our products to be easy to understand, attractive to use, and inspiring. We provide information about these products in technical documentation like guides, manuals, datasheets, leaflets, test reports, and other technical materials. To get our message across this documentation should be well structured, uniform, and easy-to-read. Also, it should be consistent across products and product versions, so that customers are more likely to stay with us.
To promote consistent and attractive technical documentation, we are providing this guide which describes how text should be organized, spelled, formatted, and so on. Not only will you find some rules here, but also ideas on how to organize your text in a more optimal way. Feel free to try these ideas and check if it makes your text more attractive or more appropriate to your audience. When doing so, you are welcome to share your opinion about how this guide can be improved.
American or British Spelling
There are several areas in which British and American spelling are different. At Espressif, we follow American spelling standards.
Difference |
American Spelling |
British Spelling |
|---|---|---|
Words ending in -er or -re |
center |
centre |
Words ending in -or or -our |
color |
colour |
Words ending in -ize or -ise |
apologize |
apologize or apologise |
Words ending in -yze or -yse |
analyze |
analyse |
Words ending in -ense or -ence |
license |
licence |
How to enable American spellcheck in word processors:
When using MS Word, go to
Review>Language, and then select(US) English.On Mac Pages go to
Edit>Spelling and Grammar>Show Spelling and Grammar, and then selectU.S. English.
If you are not sure about how to spell a word, consult the Merriam-Webster’s Collegiate Dictionary.
Active vs. Passive Voice
In both English and Chinese technical writing, when writing manuals and user guides, we use active voice and try to avoid passive voice except for rare instances. Active voice sentences are usually more engaging to the reader and easier to understand.
When you start reading a sentence in the active voice, you can clearly identify who or what performs or should perform a certain action (Press the Boot button to enter Upload mode), while passive voice sentences start with the action recipient (Upload mode is entered after pressing the Boot button) or the action itself (Entering Upload mode is done by pressing the Boot button).
When you use the passive voice, a reader may have problems distinguishing between actions by the recipient and by the user.
Example
Preferred |
Avoid |
|---|---|
Press the EN button to reset the system. |
The system is reset by pressing the EN button. |
按下 EN 键使系统复位。 |
按下 EN 键，系统被复位。 |
If a sentence in the active sounds like blaming the user, you can use the passive voice.
Example
Preferred |
Avoid |
|---|---|
If the upload fails, the serial port name may have been entered incorrectly. |
If the upload fails, you may have entered an incorrect serial port name. |
上传失败可能是因为输入了错误的串口名称。 |
上传失败可能是因为你输入了错误的串口名称。 |
You can also retain the active voice by rewording the sentence to “If the upload fails, please check the serial port name”.
Another situation when you might prefer the passive voice is to emphasize the action on the recipient or if the actor is irrelevant or unknown. This is typically the case when writing test reports, where the reader is usually more concerned with the test results rather than the party performing the testing.
Example
Preferred |
Avoid |
|---|---|
All data was recorded in the quasi-peak and average detection mode. |
I have recorded all data in the quasi-peak and average detection mode. |
所有数据均以准峰值和平均检测模式记录。 |
我以准峰值和平均检测模式记录了所有数据。 |
In formal documents, like datasheets or specifications, the passive voice can be used more frequently.
Point of View
Point of view is the perspective a writer takes in writing documentation. It determines which pronoun to use.
In technical writing, writers generally write content from the reader’s (user’s) point of view or an impersonal point of view depending on the content type. According to Diátaxis, technical documentation is classified into four major types of content: tutorials, how-to guides, references, and explanations.
Content written from the reader’s point of view focuses on what the reader needs to do.
Content written from an impersonal point of view focuses more on “things”, such as what functions a module has and how a component works with other components to achieve a specific function.
Use Second-Person Pronoun for Tutorials and How-to Guides
Write tutorials and how-to guides in second person.
Reasons
Tutorials and how-to guides aim to teach readers how to complete a task. In second person, you write as though you are speaking to the reader and the verb clearly denotes actions that they need to take, making it easier to follow.
You promote a friendly tone and keep the reader more engaged with documentation.
Typical examples of tutorials and how-to guides among Espressif documentation are:
ESP-IDF Programming Guide > Get Started, other contents that aim to help the reader to complete a specific task
TRM > Section Programming Procedure
Development Board User Guide > Section Start Application Development
When writing procedural steps, combine the second person with an imperative mood and active voice. The imperative mood makes your descriptions short and helps to eliminate the confusion around who or what performs specific procedural actions.
In Chinese, use “你” instead of “您”. During translation, you do not have to translate each “you” or “your” to “你” or “你的”. As long as the meaning is not affected, omit “你” or “你的” for fluent flow of the text.
Example
Differences between the “preferred” and “avoid” versions are highlighted in bold.
Preferred |
Avoid |
|---|---|
To set up the ESP-IDF for your ESP32, do the following:
|
These are the steps for setting up the ESP-IDF for users’ ESP32:
|
以下是为 ESP32 设置 ESP-IDF 的具体步骤：
|
以下是为 ESP32 设置 ESP-IDF 的具体步骤：
|
Use Impersonal Point of View for Explanations and Reference Materials
Write explanations and reference materials from an impersonal point of view.
Reason
When writing from an impersonal point of view, you describe from the perspective of a “thing” instead of a “person”, such as what functions or features a module has and how a component work with other components to achieve a specific function, instead of how readers interact with a component. References and explanations also focus on describing “things” and usually do not need to address the reader.
Typical examples of references and explanations among Espressif documentation are:
Chip and module datasheets
TRM > Section Registers, Section Introduction
ESP-IDF Programming Guide > Section API Reference, Section introduction for a component
Product brief
Example
See Example 2 and 3 in Section Avoid “Users” and Third-Person Pronouns (They, She, He).
Avoid “Users” and Third-Person Pronouns (They, She, He)
Avoid addressing readers as “users” and “the user” when you can. Try to reword the sentence where any form of “user” is used to address the reader.
Do not use gender-specific pronouns such as she, he, hers, and his.
Here are some examples to show how to reword sentences to avoid “user”.
Example 1
Original |
Revision |
Note |
|---|---|---|
Users can program data to the eFuse memory by writing the data to the programming register and executing the programming instruction. |
To program data to the eFuse memory, write the data to the programming register first and then execute the programming instruction. |
The example above intends to tell the reader how to program data to the eFuse memory. Use of second person, combined with imperative mood and active voice, makes it obvious who will take what actions to achieve what purpose. |
Example 2
Original |
Revision |
Note |
|---|---|---|
Users can use the hold function for the pins to retain the pin state. |
The hold function can be used to retain the pin state. |
This sentence is excepted from a paragraph dedicated to describing the pin hold function, including what the function is, how it works, and what it can achieve. So, the sentence is intended to emphasize what the function can do more than who can use that function. The revision uses passive voice to shift the focus from “users” to the function itself. |
Example 3
Original |
Revision |
Note |
|---|---|---|
CPU will be reset immediately when any type of reset above occurs. Users can retrieve reset source codes by reading LP_CLKRST_RESET_CAUSE. |
CPU will be reset immediately when any type of reset above occurs. The reset source code is stored in LP_CLKRST_RESET_CAUSE. |
The second sentence of this example is intended to describe where to get the source code. The revision introduces the word “store” to connect “source code” and the register where it is placed. |
Exception
It is OK to use “the user” (instead of “users”) and refer back with the pronouns “they” in the following cases:
When rewording makes your sentence long and hard to understand.
When the target audience of your content is developers, it is OK to use “the user” to refer to people who use the technology.
Use First-Person Singular Pronoun Sparingly (I)
In first person singular, you write as though you are speaking from the user’s point of view.
There are a small number of cases in Espressif’s documentation where use of the first-person singular pronoun is acceptable:
When writing a question in FAQs
In product user interface (UI) to show someone’s control over an action in checkbox, button, or toggle labels
When authors describe their opinions or actions in blogs or other documents
Example
Example |
Note |
|---|---|
I used ESP32 AT firmware to send Bluetooth LE scan command, but I didn’t receive any scan response packet. Why? |
This is an FAQ item written from the user’s point of view. |
I agree to the Terms of Use and Privacy Policy. |
This is displayed on the sign-up page for a mobile application called Nova Home. |
First of all, you need to find a replacement for your current PHY chip. I have a friend working for a semiconductors distribution company, so I just picked up my phone and asked him for some advice. |
This is from a blog in which the author describes his experience of how to create a new Ethernet PHY driver. |
Use First-Person Plural Pronoun Sparingly (We)
In first-person plural, you write as though you are speaking to the reader from your company’s (Espressif) point of view or you are standing by the reader’s side and making them feel that they are not alone.
There are a small number of cases in Espressif’s documentation where use of the first-person plural pronoun is acceptable:
Product Change Notification (PCN), Engineering Change Notification (ECN), advisory, etc. (to make clear Espressif is the speaker)
Blogs and books that help the reader learn something (to show that the reader is not alone)
Example
Example |
Note |
|---|---|
We will evaluate software countermeasures along with their performance impact. |
This is from an advisory. The pronoun “we” here represents Espressif. |
我们将评估软件对策及其对性能的影响。 |
|
We are committed to offering solutions that are secure, robust and power-efficient. |
This is from Section About Us on espressif.com. The pronoun “we” here represents Espressif. |
我们致力于提供安全、稳定、节能的 AIoT 解决方案。 |
In some cases, the pronoun can be omitted in Chinese translation without affecting the meaning. |
In Section XX, the starting address of the first entry in the partition table is 0x9000, rather than 0x0. Why? To answer this question, we need to look at Figure 11-3 first. |
This is from the ESP32-C3 IoT Project Development Practice book. The pronoun “we” represent both the writer and the reader. |
章节 XX 节介绍了分区表的首个条目起始地址为 0x900 0，为什么不是 0x0 这个地址呢？ 要回答这个问题，我们首先看看图 11-3。 |
When using the first-person plural pronouns, be consistent throughout the content or document and make it clear who the pronoun refers to.
Example
Original |
Revision |
Note |
|---|---|---|
Firstly, we need to use “git clone” to clone the TinyUSB project. Since some TinyUSB examples also require external submodule libraries, you can run the following command to fetch them … |
Firstly, use “git clone” to clone the TinyUSB project. Since some TinyUSB examples also require external submodule libraries, run the following command to fetch them … |
This example describes the prerequisites for running TinyUSB application examples. It is excerpted from ESP-IDF Programming Guide. The original version is not clear who the pronoun “we” refers to, the writer, the ESP-IDF developers, the writer and the reader, the company, or any other combination? For another, switching between the first person and the second person may make the reader confused. |
Avoid Switching Point of View Within a Single Content Type
Avoid switching personal pronouns (e.g., addressing the target audience as “you” and then as “they”) within a single document or across the documents of the same type. There might be an exception to this rule if a document consists of sections of different content types that require a different way of addressing described above.
A single document can contain more than one type of content. For example, in a TRM, Section Introduction is an explanation, Section Programming Procedure is a how-to guide, and Section Registers is a reference. Therefore, it might be not possible to keep consistency at the document level. In this case, try to keep consistency at a content level.
Example
Original |
To make report generation more convenient, users can define additional build targets in their projects such that the report generation can be done with a single build command. Add the following code to the [code] The following command can now be used : [command] |
Revision |
To generate reports with a single build command, define additional build targets in your project. Add the following code to the [code] Now, try the following command to generate a report: [command] |
Note |
This example is intended to tell the reader how to generate reports with a single command for convenience. It is a small how-to guide. In the original version, switching between the second person and the third person may make the reader confused about which action they should take. In the revised version, second person is combined with imperative mood and active voice, making it obvious what actions the reader should take to achieve what purpose. |
Summary
The table below summarizes which point of view or pronoun can be used in a specific document (type). For detailed guidelines, use scenarios, and examples, refer to Section Use Second-Person Pronoun for Tutorials and How-to Guides and Section Avoid Switching Point of View Within a Single Content Type.
Document (Type) |
Second Person |
Impersonal |
Third Person |
First Person (I) |
First Person (we) |
|---|---|---|---|---|---|
Tutorials and how-to guides 1 |
Y |
||||
Explanations and references 2 |
Y |
||||
FAQ |
Y |
Y |
|||
UI |
Y |
Y |
|||
Blog |
Y |
Y |
Y |
||
Documents where you need to make clear Espressif is the speaker
|
Y |
Y |
|||
Documents to show you are by the reader’s side and make them feel that they are not alone
|
Y |
Y |
|||
Documents whose target audience is developers, use “the user” to refer to people who use the technology |
Y |
- 1
Examples of tutorials and how-to guides include:
ESP-IDF Programming Guide > Get Started, other contents that aim to help the reader to complete a specific task
TRM > Programming Procedure
Dev Board User Guide > Start Application Development
- 2
Examples of explanations and references include:
Chip and module datasheets
TRM > Section Registers, Section Introduction
ESP-IDF Programming Guide > API Reference, introduction for a component
Product brief
Note that some Espressif documents are not listed in the above table. To determine which point of view or pronoun to use in these documents, check if they belong to a particular document type in this table:
If yes, use the point of view or pronoun suggested for this type of document.
If no, check if the logic that these sections use to determine which pronoun to use can inspire you, or contact Documentation Team for help.
Simplified or Traditional Chinese
We use simplified Chinese.
Define Abbreviations and Acronyms at First Use
Write out a full term for each abbreviation or acronym at its first use.
Example
Mesh development framework (MDF), not Mesh Development Framework (MDF).
If a full term is given in a heading, provide it together with the abbreviation. If this makes the heading too long, provide the abbreviation in the following text.
If an abbreviation or acronym is more familiar than the full term, then, probably, there is no need to write it out. You can also follow this abbreviation or an acronym with the full term in parentheses, e.g., USB (universal serial bus).
If a document is very long, and people are supposed to use it as a reference guide, consider establishing a section “Index of Abbreviations and Acronyms.”
If You Do Not Know How to Structure a Phrase
Check in other documents that describe a similar concept.
Look up similar phrases using refined web search techniques:
Put the key parts of your phrase inside quotes, for example: “task scheduler”.
Add “-” in front of a word you want to exclude from the search, for example: “task scheduler” - Windows.
Use synonyms of original words in your search phrase.
Look for information in monolingual dictionaries (specific computer dictionaries). Here are a couple of examples:
The Illustrated Dictionary of Electronics , published by McGraw-Hill
Microsoft Computer Dictionary , published by Microsoft Press
Oxford Dictionary of Computer Science , published by Oxford University Press
Heading Titles
In the paper and heading titles, capitalize the first letter of every word except for:
Articles (a, an, the), unless the article is the first word in the title.
Coordinating conjunctions (and, but, for, or, nor), unless the conjunction is the first word in the title.
Prepositions of four letters or less; unless these prepositions are the first or last words. Prepositions of five letters and above should be capitalized (Before, Through, Versus, Among, Under, Between, Without, etc.).
For hyphenated compounds in heading titles, always capitalize the first word, and capitalize any subsequent words that are not articles, prepositions, or coordinating conjunctions.
Example
High-Level Interrupts
ESP8266 FOTA Demonstration with Phone App
Demonstration Guide on Controlling ESP8266 Devices in IoT Cloud by Mobile Phone
Webpage titles are used to create a clickable table of contents that is often in the form of a menu on the left to navigate the document structure. Make the titles descriptive and preferably fit them within one row of text.
In Chinese text, try to avoid putting English words at the beginning of Chinese titles or sentences. If there is no other choice, do not capitalize the first letter.
Example
Preferred |
Avoid |
|---|---|
flash 加密功能 |
Flash 加密功能 |