Splunk® Style Guide

Splunk Style Guide

The guidelines in the Splunk Style Guide establish best practices for writing technical documentation. Search docs.splunk.com to find documentation related to Splunk products.

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. Note callout boxes provide important information that adds clarity to the content, and caution callout boxes provide critical information to the user before they make an irreversible decision.

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 essential to highlight your content, consider weaving that information into the introduction or as part of the instructions you're creating.

Use callout boxes judiciously. 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.
  • Don't confuse a note or caution with a prerequisite.
  • Place notes and cautions after the text they pertain to. With steps in a task, however, make sure that the user doesn't need that information before they begin the task.
  • Don't use a note or caution immediately after a topic title or section heading.
  • Include links in notes or cautions only if the link helps the reader complete the task or is essential to their understanding of the content.
  • 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 21 November, 2023
Definition lists   Note callout boxes

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

Was this topic useful?

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