Best practices for using callout boxes

Note and caution callout boxes allow you to highlight information on a page by surrounding text with a colored box.

Before you include a callout box

Before you add multiple callout boxes to a topic, consider how the callouts look on the page. They might distract readers and affect the scannability of a topic.

If a callout box isn't necessary in your content, consider weaving that information into the introduction or as part of the instructions you're creating. If the content of the note isn't relevant to your content, your reader might ignore future callout boxes.

Guidelines for using callout boxes

Follow these guidelines when you use note and caution callout boxes:

• Avoid writing long notes and cautions.
• Place notes and cautions after the text they pertain to.
• Don't confuse a note or caution with a prerequisite.
• It's okay to follow steps in a task with a note or caution, but make sure that the user doesn't need that information before they begin the task.
• Use links in notes or cautions only if including the link helps the reader be successful with the task or their understanding of the content.
• Don't use a note or caution immediately after a topic title or section heading.

Don't use other tags, styles, formatting, or words for notes and cautions inside the callout boxes. For example, don't use the term "Important" or "Tip" as a note label. The term "Warning" is used for danger and injury and is generally associated with hardware documentation.

For more guidance on when to use each type of callout box, see Note callout boxes and Caution callout boxes.