Notes, warnings, and callouts

Callouts — visually distinct blocks that highlight specific types of information — are among the most useful tools in documentation when used correctly, and among the most disruptive when overused. This article defines the four callout types used across this knowledge base, specifies when to use each, and provides guidance on placement, language, and accessibility.

This is the authoritative callout system for the knowledge base: Note, Tip, Important, and Warning. If any other article or template references a different set of callout types, this article's four types take precedence.

The Four Callout Types

Note

A note provides supplementary information that is useful but not critical. It adds context, flags an exception, or explains something that might otherwise be surprising or confusing. If the reader skips a note, nothing bad happens — they might miss something helpful, but they will not break anything.

Use a note for:

• Exceptions to a general rule described in the article
• Clarifications that apply only to specific configurations or setups
• Information that is helpful but would disrupt the flow of the main text

Label: Note
Example: Note: This setting is available only on accounts with administrator access.

Tip

A tip shares a best practice, shortcut, or recommendation that will help the reader accomplish their goal more effectively or efficiently. It is entirely optional — a reader who ignores it will still complete the task successfully.

Use a tip for:

• Shortcuts or faster ways to accomplish a task
• Best practices the reader might not discover on their own
• Suggestions that improve outcomes without being required

Label: Tip
Example: Tip: You can use the keyboard shortcut Ctrl+K to open the search bar from any page.

Important

An important callout flags information that is critical to the success of the task — something the reader must know or do to avoid a problem. It is more urgent than a note but does not indicate a risk of data loss, system failure, or security compromise.

Use an important callout for:

• Prerequisites that are not obvious
• Steps that must be done in a specific order, where doing them out of order causes the task to fail
• Settings that, if wrong, will produce incorrect results

Label: Important
Example: Important: You must complete this step before inviting additional users. Skipping it means invitees will not receive the correct permissions.

Warning

A warning signals that an action has consequences that are difficult or impossible to reverse — data loss, account deletion, irreversible configuration changes, security risk. A reader who ignores a warning and proceeds may cause significant damage.

Use a warning for:

• Actions that delete data permanently
• Actions that cannot be undone
• Security risks
• Changes that affect all users or a significant part of the system

Label: Warning
Example: Warning: Deleting a category permanently removes all articles within it. This action cannot be undone.

Placement Rules

Place callouts immediately before the content they apply to, not after. A warning that appears after the step it warns about has failed at its job — the reader may already have taken the action.

• If a callout applies to the entire article, place it at the very beginning, before the first section heading.
• If a callout applies to a specific step, place it immediately before that step — not as a sub-item within the step, and not after it.

When a step needs more than one severity level

If a single step is both a non-obvious prerequisite and carries an irreversible consequence, use only the higher-severity callout (Warning takes precedence over Important, which takes precedence over Note or Tip) and fold the lower-severity detail into that one callout's text rather than stacking two callouts on the same step. Two callouts in a row on the same piece of content dilutes both.

Nested callouts

Do not place a callout inside another callout, and avoid placing a callout inside a single list item — if the content is important enough for a callout, it should stand on its own before or after the list, not be nested inside it.

Callout Language

Keep callout content concise. A callout that runs to three paragraphs is too long — the important information will be lost in the text. If you need more than two sentences, consider whether the information belongs in the callout or in the main body of the article.

Callouts should state the key information directly, without the filler language that often creeps in: "Please note that..." / "It is important to be aware that..." / "Be advised that..." — these add no information and are the same kind of hedging the Voice and Tone guide advises against everywhere else in an article; callouts are not an exception. Start with the label, then the content.

Accessibility

A callout's type must never be conveyed by color alone. Every callout needs:

• A text label (Note, Tip, Important, Warning) at the start of the callout, not just a colored background or border.
• Sufficient contrast between the callout's text and its background, meeting the same WCAG ratios required elsewhere — see the Colors and Highlighting section of the Formatting Standards guide.
• An icon paired with, not replacing, the text label, if your design system uses icons for callouts — an icon alone is not accessible to a screen reader or to a reader who can't distinguish the icon shapes at a glance.

Avoiding Callout Overuse

The effectiveness of callouts depends on their rarity. When every section has a callout, readers start ignoring them because nothing feels more important than anything else. Reserve callouts for genuinely important information.

If you find yourself adding a note to every section, ask: is this information important enough to break the reading flow, or can it be integrated naturally into the prose? Most of the time, integrating it is the better choice.

A good benchmark: if an article has more than one warning, review whether each truly warrants the highest-level callout. If an article has more than three callouts of any type, consider whether the information could be restructured so that fewer interruptions are needed.

Summary: Callout Decision Guide

Self-Audit Checklist

Before publishing, check callouts against these questions:

• Does every callout use one of the four defined types — Note, Tip, Important, or Warning — with no ad hoc labels?
• Is each callout placed immediately before the content it applies to, never after?
• Where a step needs more than one severity, has only the highest-severity callout been used, with the rest folded into its text?
• Are callouts free of nesting inside other callouts or inside list items?
• Is callout language direct, with no "please note that" or "it is important to be aware that" filler?
• Is every callout under two sentences, with longer explanations moved to the article body?
• Does every callout carry a text label, not just a color or icon, so its type is accessible without relying on color alone?
• Does the article have three or fewer callouts total, and no more than one warning, without a clear reason for more?