Splunk® Style Guide

Splunk Style Guide

Acrobat logo Download manual as PDF

Acrobat logo Download topic as PDF

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.

Last modified on 25 May, 2022
Definition lists
Note callout boxes

This documentation applies to the following versions of Splunk® Style Guide: current

Was this documentation topic helpful?

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters