Admonitions
Admonitions are visually distinct elements within documentation that highlight information relevant to the context while standing out from the main text. Typically marked with icons, borders, or color blocks, they are especially effective for warnings, tips, notes, and other critical messages that readers should not overlook. Using consistent and clear admonitions enhances the readability and usability of technical documentation.
This chapter outlines the types of admonitions utilized in Espressif documentation, along with guidelines on their selection, formatting, and appropriate use.
Types of Admonitions
Espressif documentation incorporates the following admonition types:
Tip:
A “Tip” offers helpful advice for doing things better or more easily. Use a tip when you want to offer an optional piece of information that can enhance the reader’s experience or efficiency but is not essential to completing the task. Tips may include shortcuts, best practices, or recommended approaches for utilizing a feature.
Example:
Tip
Configure the board settings in the preferences file to save time.
Note:
A “Note” provides additional information that is directly relevant to the surrounding text. It is used to clarify or expand upon a point. Use a note when you want to provide supplementary information that is important but not critical to the main content. It enriches understanding without hindering the reader’s progress if skipped.
Example:
Note
If you use both filters on the same ADC channel, then only the first one will take effect.
Important:
An “Important” admonition highlights critical information readers need to know to achieve their goals, such as prerequisites or steps that must be followed. Use an important admonition when the information is crucial and must not be overlooked by the reader.
Example:
Important
Enabling flash encryption limits the options for further updates of ESP32-C3. Before using this feature, read the document and make sure to understand the implications.
Caution:
A “Caution” advises the reader to proceed with care, indicating a situation where improper action might lead to unexpected outcomes. Use a caution when there are negative consequences that could result from not adhering to the instructions.
Example:
Caution
Any changes or modifications not expressly approved by the party responsible for compliance could void the user’s authority to operate the equipment.
Warning:
A “warning” is a strong admonition that alerts the reader to serious dangers or severe consequences that may arise from specific actions or inactions. Use a warning when the consequences of ignoring the advice could be severe.
Example:
Warning
On ESP32-S2, when channel’s binded timer selects its maximum duty resolution, the duty cycle value cannot be set to
(2 ** duty_resolution). Otherwise, the internal duty counter in the hardware will overflow and be messed up.
Choose the Appropriate Admonition
Selecting the right admonition is essential for conveying the appropriate level of importance and urgency to readers. Here’s a step-by-step guide to help you select the correct admonition type:
Step 1: Assess the Importance
Determine the importance of the information relative to the task at hand. Is it essential for understanding or completing the task, or is it additional, helpful information?
Essential Information: Use Important, Caution, or Warning if the information is critical.
Supplementary Information: Use Note or Tip if the information is helpful but not critical.
For example, if certain settings must be configured before running a program, use an Important admonition to highlight these prerequisites; if using an alternative method can speed up the process, include it in a Tip.
Step 2: Evaluate Consequences
Consider the potential consequences if the reader ignores the information. Are there risks of errors, safety issues, legal implications, or other negative outcomes?
Minor Consequences: Use Note or Tip.
Moderate Consequences: Use Caution.
Severe Consequences: Use Warning.
For example, if the information covers minor performance tweaks, add it in a Note; if a certain configuration might cause slight compatibility issues, place it in a Caution admonition; if failure to follow the instructions could damage hardware, include it in a Warning.
Step 3: Match the Tone
Choose an admonition that matches the tone of your document. A formal document might use Caution and Warning more frequently than a casual blog post.
Formal Tone: Use Caution and Warning for serious matters.
Informal Tone: Use Tip or Note for less severe information.
For example, for a product manual, use Warning to alert readers about safety risks with electrical components; for a blog post, use a Tip to share shortcuts or personal advice.
Step 4: Consider Urgency
Determine the urgency of the information. Does it require immediate attention, or can it be considered at the reader’s leisure?
Urgent Information: Use Warning or Caution.
Less Urgent Information: Use Important, Note, or Tip.
For example, if incorrect steps could lead to an irreversible system error, use a Warning to stress the urgency; if the information describes helpful background but isn’t critical, a Note works well.
Step 5: Determine Information Type
Classify the information you want to convey:
Advice or Best Practices: Use Tip.
Additional Context: Use Note.
Critical Information: Use Important.
Potential Risks: Use Caution.
Serious Dangers: Use Warning.
For example, to encourage the use of shortcuts, include them in a Tip admonition; if a setting’s function is relevant but not critical, explain it in a Note; if prerequisites must be followed for success, use Important to highlight them; for steps that might cause minor errors if missed, use Caution; if an incorrect step could lead to injury, use Warning.
Step 6: Use Hierarchy
Follow the hierarchy of severity when selecting admonitions:
Tip < Note < Important < Caution < Warning
Start with the least severe and escalate based on the criteria above.
Step 7: Consider the Audience
Tailor the admonition to your audience. What might be a Tip for an expert could be a Note or even an Important point for a novice.
For example, if your audience includes beginners, what might be a Tip in advanced documentation could be an Important for novices.
Formatting Admonitions
Formatting Admonitions in reStructuredText Documents
In reStructuredText documents, Sphinx provides a set of standard styles for admonitions. You can use the following syntax:
.. tip::
This is a formatted tip in .rst.
.. note::
This is a formatted note in .rst.
.. important::
This is a formatted important message in .rst.
.. caution::
This is a formatted caution in .rst.
.. warning::
This is a formatted warning in .rst.
Rendering results:
Tip
This is a formatted tip in .rst.
Note
This is a formatted note in .rst.
Important
This is a formatted important message in .rst.
Caution
This is a formatted caution in .rst.
Warning
This is a formatted warning in .rst.
Formatting Admonitions in LaTeX Documents
In LaTeX, admonitions can be formatted using various packages and custom environments to ensure consistency and visual appeal.
Choosing the Right Packages
Use the mdframed package to create framed environments for admonitions. It provides precise control over frame appearance, including colors, borders, and spacing. Also, include the xcolor package to enable the use of custom colors in the frames.
\usepackage{mdframed}
\usepackage{xcolor}
Defining Custom Colors
In LaTeX documents of Espressif, it is recommended to use the following colors for admonitions.
\definecolor{ForestGreen}{HTML}{2C6B2F}
\definecolor{GoldenDreamColor}{HTML}{1020A0}
\definecolor{DarkOrange}{HTML}{D46B2D}
\definecolor{AllportsColor}{HTML}{A02010}
Defining Translation Commands
For multilingual support, define the translations for admonition titles. Below are the suggested translations used in LaTeX documents of Espressif.
% Tip
\DeclareTranslation{English}{framedtxttip}{Tip:}
\DeclareTranslation{chinese}{framedtxttip}{提示：}
% Note
\DeclareTranslation{English}{framedtxtnote}{Note:}
\DeclareTranslation{chinese}{framedtxtnote}{说明：}
%Important
\DeclareTranslation{English}{framedtxtimportant}{Important:}
\DeclareTranslation{chinese}{framedtxtimportant}{重要：}
% Caution
\DeclareTranslation{English}{framedtxtcaution}{Caution:}
\DeclareTranslation{chinese}{framedtxtcaution}{警告：}
% Warning
\DeclareTranslation{English}{framedtxtwarning}{Warning:}
\DeclareTranslation{chinese}{framedtxtwarning}{危险：}
Defining Admonition Environments
Add the following definitions to the preamble:
% Tip
\newenvironment{tiplisting}
{\small\mdframed[middlelinewidth=0.5pt, middlelinecolor=ForestGreen, skipabove=15pt]{ \textbf{{\color{ForestGreen} \GetTranslation{framedtxttip}}}}}
{\endmdframed\vspace{12pt}\normalsize}
% Note
\newenvironment{notelisting}
{\small\mdframed[middlelinewidth=0.5pt, middlelinecolor=GoldenDreamColor, skipabove=15pt]{\textbf{{\color{GoldenDreamColor} \GetTranslation{framedtxtnote}}}}}
{\endmdframed\vspace{12pt}\normalsize}
% Important
\newenvironment{importantlisting}
{\small\mdframed[middlelinewidth=0.5pt, middlelinecolor=DarkOrange, skipabove=15pt]{\textbf{{\color{DarkOrange} \GetTranslation{framedtxtimportant}}}}}
{\endmdframed\vspace{12pt}\normalsize}
% Caution
\newenvironment{cautionlisting}
{\small\mdframed[middlelinewidth=0.5pt, middlelinecolor=AllportsColor, skipabove=15pt]{\textbf{{\color{AllportsColor} \GetTranslation{framedtxtcaution}}}}} {\endmdframed\vspace{12pt}\normalsize}
% Warning
\newenvironment{warninglisting}
{\small\mdframed[middlelinewidth=0.5pt, middlelinecolor=AllportsColor, skipabove=15pt]{\textbf{{\color{AllportsColor} \GetTranslation{framedtxtwarning}}}}}
{\endmdframed\vspace{12pt}\normalsize}
Applying Admonitions in Documents
After defining the environments, use them in the document as follows:
\begin{tiplisting}
\item Configure the board settings in the preferences file to save time.
\end{tiplisting}
\begin{notelisting}
\item Keep the port name handy as you will need it in the next steps.
\end{notelisting}
\begin{importantlisting}
\item Enabling flash encryption limits the options for further updates of ESP32-C3. Before using this feature, read the document and make sure to understand the implications.
\end{importantlisting}
\begin{cautionlisting}
\item Any changes or modifications not expressly approved by the party responsible for compliance could void the user’s authority to operate the equipment.
\end{cautionlisting}
\begin{warninglisting}
\item The transport should be valid during the client lifetime and is destroyed when esp\_mqtt\_client\_destroy is called.
\end{warninglisting}
Rendering results:
Examples of Admonitions in LaTeX
Usage Guidelines
Consistency:
Maintain a uniform style for each admonition type across all documentation, including icons, borders, colors, and message descriptions.
Relevance:
Ensure that each admonition is relevant to the topic at hand.
Admonitions should provide value to the reader and enhance their understanding or execution of the task.
Irrelevant or loosely related information should not be elevated to an admonition.
Placement:
Position admonitions near related content.
Do not bury important admonitions at the end of a section or chapter, as they may be overlooked.
Frequency:
Use admonitions sparingly to maintain their effectiveness. Avoid overusing “Warning” or “Caution” admonitions, as this can lead to alert fatigue, where readers start to ignore them.
Localization:
Translate admonitions (including both titles and content) while maintaining the same level of severity and meaning as in the original text.
Below are the Chinese translations for the titles of the five types of admonitions utilized within Espressif Documentation:
Tip: 提示
Note: 说明
Important: 重要
Caution: 警告
Warning: 危险