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.

Show symbols in text

If you use a symbol in a sentence, spell out the text equivalent for the symbol first. Using symbols as a substitute for words can introduce reader confusion, and not all symbols are culturally understood or read contextually by screen readers. See Spell out words and symbols in Write accessible documentation for more information.

Introduce a symbol as a noun in a sentence

When you want to introduce a symbol as a noun in a sentence, write the spelled-out form of the symbol first, and then refer to the symbol in parentheses with nonbreaking spaces. The HTML character entity for a nonbreaking space is  .

Review the following table for examples of how to correctly show symbols as nouns in text:

Do this Don't do this
Begin the line with a forward slash ( / ). Begin the line with a forward slash, /.
Enter your search after the pipe ( | ). Enter your search after the | character.

Avoid using symbols as abbreviated words

Avoid substituting symbols for words in sentences or tables in an attempt to reduce character count.

Spell out words like "and", "plus", "minus", and "about" instead of using a corresponding symbol. Rather than using the right-pointing angle bracket to describe menu paths, use an equivalent word like "then". See more in Brackets.

Review the following table for examples of writing out text equivalents instead of relying on symbols:

Do this Don't do this
Apps and add-ons Apps & add-ons
Begin your time offset with a plus ( + ) or minus ( - ) to indicate the offset from the current time. Begin your time offset with +/- to indicate the offset from the current time.
It can take about 5 minutes for your host to display in the user interface. It can take ~5 minutes for your host to display in the user interface.
In Splunk Web, select Settings, then Advanced Search. In Splunk Web, select Settings > Advanced Search.

If you're writing UI text and you don't have space to write out the name of the symbol, use hidden text such as the aria-label attribute to define the symbol.

Exceptions to spelling out symbols

In some cases, it's acceptable to use symbols without first spelling out the text equivalent. The following table includes some scenarios:

Scenario Example
As grammatical punctuation
  • Commas
  • Terminal punctuation
  • Quotation marks
In string literal
  • Code formatting
  • Command syntax
  • Programming and scripting languages
  • Special characters in URLs or file paths
In keyboard shortcuts Ctrl+Alt+Del
As angle brackets offsetting a placeholder value host=<your_hostname>
As a percent sign after a number 10%
In mathematical equations (3.14 * diameter)

What to call symbols

Use the following terms when referring to a symbol as a noun in Splunk documentation:

Symbol What to call it
` Backtick
~ Tilde
! Exclamation point
@ At symbol
# Pound sign, number sign, hash mark
$ Dollar sign
% Percent sign
^ Caret
& Ampersand
* Asterisk, wildcard
( Left parenthesis
) Right parenthesis
- Dash, hyphen, minus sign
_ Underscore
= Equal sign
+ Plus sign
[ Left bracket
] Right bracket
{ Left brace, left curly brace
} Right brace, right curly brace
\ Backslash
| Pipe, vertical bar
; Semicolon
: Colon
' Single quotation mark, apostrophe
" Double quotation mark
, Comma
< Less than, left-pointing angle bracket
. Period, dot, or point depending on context. See Period.
> Greater than, right-pointing angle bracket
/ Forward slash
? Question mark
Last modified on 22 February, 2024
Versions   Ampersand

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