Words
Introduction
Technical documentation relies heavily on the clarity, precision, and accuracy of words. While it may seem obvious, well-constructed sentences begin with carefully chosen words. This chapter outlines essential guidelines for word usage to ensure technical writing is consistent, clear, and unambiguous.
Define New or Unfamiliar Terms
When writing technical content, identify terms that may be unfamiliar to the reader. Clarifying unfamiliar terms ensures that the reader stays focused on the content without being confused by unexplained jargon. When identifying such a term, take one of the following two tactics:
If the term has already been defined in the term base (an HTTPS link to be added), link it to the existing definition rather than redefining it.
If your document is introducing a new term, provide a clear definition when it first appears. If your document introduces many new terms, consolidate their definitions into a glossary as follows:
A Glossary
Use Terms Consistently
Use terminology consistently throughout your document. Once you introduce a specific word or term, do not replace it with synonyms or alternative terms that could confuse the reader. Inconsistent terminology can lead users to think there is a subtle distinction between the terms, creating unnecessary confusion.
Preferred |
Avoid |
|---|---|
SPIFFS is a file system intended for SPI NOR flash devices on embedded targets. It supports wear levelling, file system consistency checks, and more. |
SPIFFS is a file system intended for SPI NOR flash devices on embedded targets. It supports wear levelling, filesystem consistency checks, and more. |
To simplify long or complex terms, provide a shortened version when first introducing the concept. You may use the shortened form consistently after this point.
Example
If this address is close to zero, it usually means that the application has attempted to access a member of a structure (or struct for short), but the pointer to the struct is NULL.
Use Abbreviations Properly
Define Abbreviations at First Use
Write out the full term when an abbreviation is introduced, and include the abbreviation in parentheses immediately after the term. It is also recommended emphasizing both the term and abbreviation by using boldface.
Example
A Device under test (DUT) is a set of ESP chip(s) which connect to a host (e.g., a PC).
Once the abbreviation has been defined, you may use the abbreviation alone throughout the rest of the document:
Example
A Device under test (DUT) is a set of ESP chip(s) which connect to a host (e.g., a PC). The host is responsible for flashing the apps to the DUT, triggering the test cases, and inspecting the test results.
Note
If the full term is used in a heading, include the abbreviation alongside it. If this makes the heading too long, define the abbreviation in the first sentence of the following section.
When to Use Abbreviations
Abbreviations can improve readability by shortening repeated terms, but they also add a layer of abstraction. The reader must mentally expand abbreviations into their full meaning, which may initially slow comprehension.
To determine whether to use an abbreviation, follow these guidelines:
Avoid abbreviations that are only used a few times in a document.
- Use abbreviations that meet both of the following criteria:
The abbreviation is significantly shorter than the full term.
The abbreviation is used frequently throughout document.
Note
If an abbreviation is more familiar than the full term, you may use it without defining it. You can also follow this abbreviation with the full term in parentheses, e.g., USB (universal serial bus).
If a document is very long, and the reader is supposed to use it as a reference guide, consider establishing a section “Index of Abbreviations and Acronyms”.
Avoid switching back and forth between the acronym and the full term. Use one consistently.
Preferred
Avoid
This component allows C library functions, such as fopen and fprintf, to work with FS drivers. At a high level, each FS driver is mounted at some path prefix.
This component allows C library functions, such as fopen and fprintf, to work with FS drivers. At a high level, each filesystem driver is mounted at some path prefix.