Callouts and admonitions¶
Callouts emphasize important or helpful information that is not part of the text flow. Readers may skip callouts since they are outside of the paragraph. To test if something should be a note or warning, write the text first as part of the paragraph and then decide if you need to make the information a callout.
Do not use too many callouts. When you use too many notes they lose their effectiveness and blend into the other information.
Do not use a callout that provides information that the user needs to succeed with the task.
The following callouts are used:
| Name | Description |
|---|---|
| Tip | Provides helpful suggestions or useful information to improve user experience or provide alternative ways of doing something |
| Important | Provides essential points to complete a task or understand a topic |
| Warning or Caution | Highlight critical information that users must be aware of to avoid data loss, system misbehavior, etc. |
| Note or Info | Provides information to supplement the main idea and /or help users better understand the topic. Also provides information that applies in certain cases |
| See also | Provides additional materials (common cases, deeper context) that are related to the preceding text. |
| Example | Highlights examples |
Rules¶
- Separate callouts with text paragraphs
- Don’t group callouts together. Reorganize the content.
- Avoid using a code-block inside callouts
When to use the callout¶
Create a callout when:
-
The information is not necessary for what the user is doing. Even if the user skips the information in the callout, the task succeeds.
-
The information is outside of the flow of the task.
Created: June 26, 2023