EMoS Quick Reference Guide
This reference sheet is intended to provide quick access to basic guidelines about writing English documents in the Espressif Manual of style. For more detailed information and examples, please refer to the full manual.
Active Voice
When writing manuals and user guides, use active voice and avoid passive voice except for rare instances.
Example
Press the
ENbutton to reset the system.
In formal documents, like datasheets or specifications, passive voice can be used more frequently.
Example
ESP32-S2 is designed for ultra-low-power applications with its multiple low-power modes.
Refer to Section Active vs. Passive Voice for more details.
Point of View
Write tutorials and how-to guides in second person.
Example
To program data to the eFuse memory, write the data to the programming register first.
Write explanations and reference materials from an impersonal point of view.
Example
The hold function can be used to retain the pin state.
Avoid using “users”, “the user” or third-person pronouns when you can.
Avoid switching point of view within a single content type.
Refer to Section Point of View for more details.
Abbreviations and Acronyms
Spell out abbreviations and acronyms on first mention except when they are more familiar than full terms.
Example
Mesh development framework (MDF)
USB
Refer to Section Define Abbreviations and Acronyms at First Use for more details.
Capitalization
Capitalize the first letter of every word in heading titles, figure and table captions, except for articles, coordinating conjunctions, and prepositions of four letters or less.
Example
ESP8266 FOTA Demonstration with Phone App
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
Capitalize the first letter of each item in a list of complete sentences.
Refer to Section Heading Titles for more details.
Punctuation
Use English punctuation in English writing and Chinese punctuation in Chinese writing except for rare cases.
Spaces
Use spaces between a number and the following unit of measure.
Example
40 nm
Use spaces between an English punctuation mark and the following English word.
Example
In mixed writing of English and Chinese, use spaces by following rules provided in EMoS.
Use spaces between Chinese characters and English letters.
Example
USB 接口
Never use spaces between English ( ), ” “, ‘ ‘ and the enclosed text.
Example
(MDF)
Never use spaces between a number and the percentage sign %.
Example
50%
Never use spaces between a number and the angle sign °.
Example
50°
Never use spaces when specifying a version number of a document or software application.
Example
v1.1
Never use spaces around ampersand in abbreviations containing the word “and”.
Example
R&D
Hyphens/en Dashes
Use hyphens in a compound modifier preceding the modified word that consists of a noun or adjective and a present or past participle, or consists of a number, single letter, or fraction and a noun or participle.
Example
State-of-the-art technology
Wi-Fi-enabled toys
2-bit data length
Use en dashes to indicate a range of values, without spaces before and after.
Example
2019-2020
Use en dashes to indicate negative numbers.
Example
–1
Slashes
Do not use slashes as a substitute for “or”.
Oxford Comma
Use Oxford Comma before the conjunction that joins the last two enumerated items within a sentence.
Example
The table should provide separate columns for user IDs, their first names, and last names.
Punctuation in Lists
Use a full stop at the end of each item in a list of complete sentences.
Do not use punctuations at the end of each item in a list of sentence fragments.
Refer to Chapter Punctuation for more details.
Numbers
In general, spell out numbers one through nine, and use numerals for numbers 10 and higher. There are many exceptions when numerals are preferred. Common exceptions include:
a single-digit whole number used as an adjective
measurements
time and dates
percentages
parameter values
Example
5-year period
1 bit
8:00
5%
Use a comma “,” to mark off groups of three digits for numbers of five digits or more.
Example
10,000
Write decimals with a period (full stop), not a comma.
Example
1.4
When referring to money, use currency code, instead of currency signs.
Example
100 USD
In general, decimal and hexadecimal numbers are recommended.
Refer to Chapter Numbers for more details.
Times and Dates
Use 24-hour system instead of 12-hour system if possible.
Example
15:00 Beijing Time
Use “noon” or “midnight” instead of figures.
Use ordinal numbers to indicate a date, without st, nd, rd, or th.
Example
June 4
Do not use all-numeral style to indicate a date.
Example
04/06/2020 NOT acceptable
When a phrase refers to a month, day and year, set off the year with commas.
Example
June 1, 2020, was the International Children’s Day.
When a phrase lists only a month and year, spell out the month and do not separate the month and the year with commas.
Example
The new website will launch in December 2024.
Use three-letter abbreviations without dots for months.
Example
Jan, Jun, Dec
Use three-letter abbreviations without dots for days of the week.
Example
Mon, Thu, Sun
Refer to Chapter Time and Dates for more details.
Measurements
Use spaces between a number and the following unit of measure.
Use correct measurements units and their abbreviations. Some frequently used units of measure are:
Byte, <abbr> B
kilobyte, <abbr> KB
kilohertz, <abbr> kHz
megabit, <abbr> Mbit
megabits per second, <abbr> Mbit/s
megahertz, <abbr> MHz
Example
85 °C
Refer to Chapter Measurement Units and Abbreviations for more details.
Cross-References
Use descriptive text for hyperlinks not blank expressions, such as “click here”.
In LaTeX, Word, or Pages documents, follow the rules below:
Use color blue (Hex Color #0096FF) and underline to indicate external hyperlinks.
Use color blue, underline, and italics when referring to English titles of articles, books, etc.
For
.mdor.rstdocuments, follow the existing style.
Refer to Chapter Editing References for more details.
Pictures and Diagrams
Text in pictures should be of similar size as the document’s body text.
Place figures immediately after the paragraph in which they were mentioned.
Pictures should be center-aligned.
In most cases, add numbering and captions under a figure.
Figures and their captions should stick together.
Refer to Chapter Pictures and Diagrams for more details.
Formatting Tables
Apply center alignment vertically for text in cells.
The default horizontal alignment in table cells is to the left for text and to the right for numbers, except for rare cases.
If a column is right-aligned, that is normally the case for numbers, then the head should be centered.
Numbers that include decimal points are usually aligned to the decimal point.
Align the column heads vertically to the bottom.
Center-align tables on a page.
Use em dash (—) for not applicable data. It is fine to omit em dash, if the table contains the same kind of data.
Refer to Chapter Tables for more details.
English Grammar Tips
The indefinite article (a/an) depends on the sound, not the letter, that comes after the indefinite article.
Example
a USB (starts with /j/)
an hour (starts with /au/)
In most cases, use present tense when describing procedures and tasks.
Avoid using contractions, such as it’s, don’t.
Refer to Chapter English Grammar Tips for more details.
Avoid Common Chinglish
Common Chinglish include:
Unnecessary category nouns, such as function, work, process
Unnecessary verbs, such as conduct, make
Repetition of ideas presented in both positive and negative form
Chinglish collocations, such as “learn knowledge”
More than three nouns combined into an adjective
Adverbs misused as a conjunction
Refer to Chapter Avoid Common Chinglish for more details.
Referring to UI Elements
Write out the UI element text exactly as it appears in the interface, but do not include the end punctuation if there is any.
In
.mdor.rstdocuments, use double backquotes (``) to enclose the UI element text.In LaTeX, Word, or Pages documents, follow the rules below:
Use boldface for English elements in English document.
Example
Click Submit.
Use double quotation marks for UI elements in other cases.
Example
Click “Submit”.
Click “提交”.
Use a greater-than symbol (>) to indicate navigation through UI elements and include a space before and after the symbol.
Example
In the Start window, on the Insert tab, click Table > Insert Table.
Use the UI element text in the same language (EN/CN) as the document language if the corresponding language option is available in the interface. Otherwise, use the source UI element text or follow the text with your translation in a bracket to add clarity.
Example
Say the wake-up word “Hi 乐鑫” (“Hi Espressif”) to activate the board.
Refer to Section UI Elements for more details.
Referring to Software and Hardware Modes
In general, use title capitalization for the mode name except for the word “mode”.
Do not use the definite article “the” before mode names.
Example
Flash encryption should be enabled in Release mode only.
Refer to Section Software and Hardware Modes for more details.
Technical Terms
Use technical terms consistently within one document or across all project-specific documents.
Always consult Espressif Term Base if you are not sure about a certain technical term.