Callouts direct your attention to information of special importance or to information that doesn't fit smoothly into the main text. Consider your reader. If your doc has too many callouts, it might confuse your reader about what matters the most and distract them from what does.
Use your callouts judiciously. Recommendation: Skim the complete doc. If there are too many callouts, decide which ones can be removed.
Types of callouts
We have a number of callout types, and each is controlled by the variant
you include in the <Callout>
tag.
Here's an example of the format for a tip callout:
<Callout variant="tip"> Your tip text goes here.
It can have multiple paragraphs.</Callout>
Here are examples of our callout variants:
Avoid callout fatigue
Callout fatigue is what happens when there are too many callouts on a doc. A single callout is a great way to draw attention to important information, but the more callouts there are, the more likely it is that your reader won't read the callouts.
Keep these things in mind when you're working with callouts:
- If you add a callout, remove a callout. Wherever possible, don't increase the number of callouts.
- Do not use stacked callouts. Stacked callouts are two or more callouts that follow directly one after another. Not only do not use these, but if you see this in a doc, take a few minutes to break these callouts up.
- Remove outdated callouts. As you're going through the docs site, if you see a callout that's outdated, for whatever reason, take a few minutes to delete it from the doc.
- Be stingy in your use of important and warning callouts. If we use important and warning callouts too often, they lose their effectiveness.
Stacked callouts example
Here's an example of the stacked callouts we'd love to avoid.
Tip
The more callouts there are, the more difficult it is to spot the information that's important.
Important
Not everything is important enough to put in a callout.
Caution
Think carefully before adding another callout on the page.