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.

Use device-agnostic language

Customers interact with Splunk software using many kinds of devices and input methods, such as mobile devices and voice commands. Unless you know that customers use a product only on a certain device, assume that Splunk software works across a range of devices. Device-specific words like "click" and "type" aren't inclusive to all users and the ways they interact with the software.

To write for Splunk customers who use a variety of devices, including keyboards, mice, mobile devices, speech-to-text software, screen readers, and other assistive and adaptive technologies, use device- and input-agnostic language in your docs.

Focus on the action, not on the gesture

Device-specific language like "double-click" and "right-click" doesn't consider users who use keyboards and mobile devices. Words like "press" and "tap" don't consider users who interact with touch screens through voice commands.

If you're tempted to use a device-specific gesture when the user has the option to use a number of devices, think of an inclusive term that focuses on the action a user performs instead of the motion they take on a device.

"Enter" and "select" work well for most situations and devices.

Enter

Use "enter" when referring to the inputting of text. Review the following table for examples of using "enter":

Do this Don't do this
For the Destination field, enter ca_counties. For the Destination field, type ca_counties.
Enter your password. Type your password.
Enter your search in the search bar. Type your search in the search bar.

Select

Use "select" when referring to highlighting text, clicking a link, choosing menu items, clicking a button or tab, pressing keys on a keyboard, or interacting with a touch-based user interface. Review the following table for examples of using "select":

Do this Don't do this
Select the text that you want to copy. Right-click the text that you want to copy.
Select the link. Click the link.
Select the container folder to open it. Double-click the container folder to open it.
Select a time period from the drop-down menu. Choose a time period from the drop-down menu.
Select Modify. Click Modify.
Select the Patterns tab. Click the Patterns tab.
Select Esc. Press Esc.
Select a dashboard to view it. Tap a dashboard to view it.

What if "enter" and "select" don't work?

As much as possible, avoid language that's specific to any single device or input option. You can use other device-agnostic terminology if those verbs fit the situation better. Here are some examples:

  • Check
  • Navigate to
  • Open
  • Remove
  • Toggle
  • Uncheck
  • Undo
  • Zoom in

If you know that customers must perform an action in a specific way on a particular device, it's acceptable to use device-specific language to describe how they perform that function. For example, you might describe the physical interaction needed to scan a 3D object in Splunk AR for iOS on an iPhone or iPad.

To find mobile terminology and other terminology replacements, see the Usage dictionary.

Last modified on 31 January, 2024
Write unbiased documentation   Capitalization

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