Splunk® Style Guide

Splunk Style Guide

Acrobat logo Download manual as PDF


Acrobat logo Download topic as PDF

Use device-agnostic language

Customers interact with Splunk software using many kinds of devices, including mobile devices, and various input methods, including voice commands. Unless you know that a customer uses an app or product on a certain device only, assume that Splunk apps and products work across a range of devices. Words like "click" and "type" aren't inclusive to all users and all the ways they interact with the software.

To write for users who interact with Splunk products using a variety of devices, including keyboards, mice, mobile devices, speech to text, 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. See the following examples:

  • For the Destination field, enter ca_counties.
  • Enter a password value.
  • Enter 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. See the following examples:

Correct Incorrect
Select the text that you want to copy. Right-click the text that you want to copy.
Select the link. Click the link.
Select a time period from the drop-down menu. Choose a time period from the drop-down.
Select Modify. Click the Modify button.
Select Patterns. Click the Patterns tab.
Select Escape. Press Escape.
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 "check", "navigate to", "open", "remove", "toggle", "uncheck", "undo", "zoom in", or other device-agnostic terminology if those verbs fit the situation better.

If you know that customers must perform an action in a particular way on a particular device only, such as scanning a 3D object in Splunk AR for iOS on an iPhone or iPad, it's acceptable to use device-specific language to describe how they perform that function, including the gestures and physical movements they take with their mobile device.

You can find mobile terminology and other terminology replacements in the Usage dictionary.

Last modified on 27 April, 2023
PREVIOUS
Write unbiased documentation
  NEXT
Capitalization

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