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.
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.
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:
|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 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 "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.
Write unbiased documentation
This documentation applies to the following versions of Splunk® Style Guide: current
Feedback submitted, thanks!