UI text style guidelines

These guidelines provide a quick reference for anyone who writes user interface (UI) text at Splunk. The purpose of UI text is to help users achieve their goals by guiding them through the product interface.

Much of the guidance for Splunk documentation and UI text overlaps. If you can't find the guidance you're looking for in the UI text style guidelines, use the guidance provided in other sections of the Splunk Style Guide.

Terminology and word usage

Use terms consistently across products and docs. See the following resources for guidance on word usage, product terminology, abbreviations, voice and tone, and more:

Topic	Link
Terms to use and avoid	Usage dictionary
Product terminology	Splunk product terminology
Splunk-specific terminology definitions	Splexicon
Abbreviations	Abbreviations
Acronyms and initialisms	Acronyms and initialisms
Punctuation	Punctuation and symbols
Voice and tone	Tone Use plain language Be active and present Write in indicative or imperative mood
Unbiased language	Write unbiased documentation Use device-agnostic language

Capitalization

Use sentence-style capitalization for all text in Splunk product UIs, including headings. In sentence-style capitalization, capitalize only the first word and proper nouns, such as product names. Don't capitalize the names of features or components. Don't use capitalization for emphasis.

The following examples show sentence-style capitalization:

UI text element	Correct	Incorrect
Button label	Create dashboard	Create Dashboard
Dialog box title	Edit schedule	Edit Schedule
Explanatory text	Indexer clusters are groups of Splunk indexers configured to keep multiple copies of data.	Indexer Clusters are groups of Splunk Indexers configured to keep multiple copies of data.
Field label	Indexed fields	Indexed Fields
Page title	Data models	Data Models
Section heading	Dashboard groups	Dashboard Groups

Terminal punctuation

Follow these best practices for terminal punctuation:

• Use a period at the end of complete sentences.
• When writing single, short, descriptive phrases that are not complete sentences, don't use a period at the end.
• If a UI element requires more than one phrase of description, write them as sentences and use a period or other appropriate punctuation to distinguish them from one another and to enhance readability.
• If a word or phrase is meant to be read as a question, use a question mark.
• Don't use exclamation marks.
• If a single view, page, or dialog box contains descriptive text that uses both full sentences and fragments, try rewriting the full sentences into fragments. If it isn't possible to rewrite the full sentences into fragments, use terminal punctuation for all of the text for consistency.

For more punctuation guidelines, see Punctuation and symbols.

See the following examples of correct and incorrect punctuation:

Correct	Incorrect
The search head removes the alias field from the event.	The search head removes the alias field from the event
Search results	Search results.
The search processed 100,000 events. This process took less than a minute.	The search processed 100,000 events, this process took less than a minute.
What is the average query response time?	What is the average query response time
The update includes enhanced security features.	The update includes enhanced security features!

Text formatting

Avoid applying special formatting to text in the UI whenever possible because it introduces visual noise and complexity. Use the typography and styles defined in the design system for headings and paragraph text.

Use the following formatting guidelines:

• Avoid referring to UI elements in the UI. If you're writing in-product documentation, such as for a guided workflow, and you need to refer to UI elements, follow the documentation formatting guidelines in Formatting reference.
• Don't use formatting like bold, italics, or monospaced font in microcopy such as tooltips, help text, field labels, button labels, and error messages.
• Don't use all capital letters or bold to emphasize a word.
• Use indicating nouns to provide context for commands or other code elements rather than using monospaced font for the code element.

See the following examples:

Correct	Incorrect
Enter your email address.	Enter your email address.
Use the map_get() function to extract nested values from the attributes field.	Use map_get() to extract nested values from attributes.
The maximum number of search jobs has been reached. To reduce the number of search jobs, go to Job Inspector and delete unneeded jobs.	The maximum number of search jobs has been reached. To reduce the number of search jobs, go to Job Inspector and delete unneeded jobs.

Possessive pronouns

Avoid using possessive pronouns such as "my" and "your" in page names, menu names, and titles. For example, instead of "My Settings", use "Settings". Instead of "Your Workspaces", use "Workspaces".

It's okay to use possessive pronouns in instructional and error message text, such as "Enter your password."

Numbers

In general, use numerals for numbers that appear in the UI, including 0 through 9. Avoid starting a sentence with a numeral.

If a number's numerical value is not the focus of the sentence, spell the number out, as in the following example: "Move an app from one instance to another."

For more guidance on numbers and examples, see Using numbers in text.

Time

When writing about time, follow the guidelines in the Time topic. If you need to abbreviate units of time due to space constraints in a Splunk product UI, use these guidelines:

Unit	Abbreviation
day	d
hour	h
microsecond	Don't abbreviate.
millisecond	ms
minute	min
month	mo
nanosecond	Don't abbreviate.
second	sec
week	wk
year	yr

Symbols

If you need to use a symbol in text, write out the name of the symbol first, and then refer to the symbol in parentheses with nonbreaking spaces. The HTML character entity for a nonbreaking space is  . See the following example:

Correct

Enter your search after the pipe ( | ).

Incorrect

Enter your search after the |.

See Show symbols in text for more information on how to use symbols and what to call them.

If you don't have space to write out the name of the symbol, you can use hidden text such as the aria-label attribute to define the symbol. See Spell out words and symbols for more information.

Links

Never surprise a user with where a link takes them. Use descriptive labels for links so users know where they're going and what they'll find if they select the link.

Follow these general guidelines:

• Keep the link text brief while still providing enough context to convey where the link takes the user.
• Don't use phrases like "click here" or "here" as link text.
• Link judiciously. Too many links are a distraction.

You can use the following types of links:

• Links in a sentence
• Standalone links
• Learn more links

Links in a sentence

Follow these guidelines for links in a sentence:

• Include no more than one link in a single sentence.
• Don't link the entire sentence, only the text that describes the action or where the user goes when they select the link. If it's a very short sentence that only describes the action, it's okay to link the entire sentence.
• Don't place links that navigate outside of the application inside of a sentence. Use a standalone link instead.
• Don't link to Splunk product documentation in a sentence. Use a Learn more link.

The following table shows correct and incorrect examples of links in a sentence:

Correct	Incorrect
Start getting data in on the Connect Your Data page.	If data has not been ingested yet, click here to initiate the GDI setup.
View and manage your table views on the Datasets page.	Go here to view and manage your table views.
Manage team schedule.	Click here to manage team schedule.
To monitor infrastructure, install the Splunk Wizbang product.	If you're interested in monitoring infrastructure, start by installing the Splunk Wizbang product or other integrations.

Standalone links

A standalone link is a link that is not part of a sentence. Follow these guidelines for standalone links:

• Use a standalone link with the external link iconfor links that navigate outside of the application.
• Don't use punctuation.
• If you need to link to Splunk product documentation, use a Learn more link.

The following table shows correct and incorrect examples of standalone links:

Correct	Incorrect
View on Splunkbase	Download the app.
View AWS docs	Review the AWS documentation.
Download Ansible	Ensure that you have Ansible 2.9+ installed.

Learn more links

A Learn more link is a type of standalone link. Use a Learn more link to link to Splunk product documentation from a page or dialog box in the UI. Don't use a Learn more link for links to third-party documentation or other resources or websites. Don't include a Learn more link in a sentence, and always place the Learn more link after related descriptive or explanatory text.

When deciding where to include a Learn more link in the UI, identify the most complicated concepts in the product workflow where a user might need supplemental information. Consider whether a tooltip can display the same content without needing to link out of the product. If a user might need more information than what a tooltip can provide, add a Learn more link to the appropriate documentation.

Follow these guidelines for Learn more links:

• Capitalize the first word only. For example: Learn more
• Don't use punctuation.
• Don't add any text after the Learn more link.
• Never refer to a specific doc manual in text that precedes the Learn more link.
• Always follow the text with the external link icon:.This icon means that the link opens in a new tab.
• Hyperlink both the text and the icon.
• Don't put a Learn more link inside of a tooltip.

The following table shows correct and incorrect examples of Learn more links:

Correct	Incorrect
	To learn more about the Splunk Wizbang product, read the documentation.

Here's an example of a Learn more link to instructions for updating the Splunk OpenTelemetry Collector Ansible roles that is preceded by a sentence that provides context for the link:

Field labels

All fields must have labels. Place field labels outside of the field box, not inside the field box. Text inside the field box disappears when the user selects it which means users can't see the field label to check their work after they've entered information in the field.

Use sentence-style capitalization for field labels.

Help text

Help text is a concise statement or phrase that gives users context about fields in the product UI. Provide help text outside of the field box. Put information that's essential to completing the task in help text rather than in a tooltip so that it's always visible.

Help text is an opportunity to clarify. Think about these questions when writing help text:

• How long does this field need to be?
• Who sees this field?
• Where does this field appear?
• Can the user change this field later?
• What is the difference between this field and another one?

Placeholder text

Placeholder text is located inside a field box. Don't use placeholder text for these reasons:

• Placeholder text disappears when the user types in the field straining short-term memory.
• Using both help text and placeholder text can be redundant and clutter up the form.
• Empty fields catch the eye better than fields with text in them.

Use help text or a tooltip to provide hints or instructions for filling in the field.

Tooltips

Tooltips identify or add a small amount of information to a UI element. Use tooltips to help users understand the meaning or purpose of icons or fields.

Use tooltips for supplemental information only. Don't put essential information in a tooltip because users might miss it. Put information that's essential to completing the task in help text next to the UI element so it's always visible.

When writing a tooltip, use these guidelines:

• Be short and concise.
• A tooltip can vary in length from one word to a couple short sentences.
• If the UI element requires a lengthy explanation, consider a different design or use a Learn more link to the product documentation instead of a tooltip.
• Use sentence-style capitalization.
• Use a period to punctuate full sentences. If the tooltip is a short phrase or the name of a tool or icon, don't punctuate the tooltip with a period.
• Use present tense.
• Don't use "please".
• Don't include interactive elements such as links or buttons in tooltips.

The following table shows tooltip examples that are revised to provide clarity and adhere to tooltip guidelines:

Original tooltip	Rewritten tooltip
Please enter a name for the model so you can refer to it later. You might include information like the name of the dataset, the field you are predicting, or the algorithm being used.	Enter a name for the model. Include information like the dataset name, the field you're predicting, or the algorithm being used.
Maximum time	Specifies the maximum amount of time that a summary-creating search can run. Enter 1 hour to ensure proper summary creation for most data models.
This view helps to get a sense of how groups with similar type of distribution are similar to each other. Do you see that the histogram of mean and standard deviations are very sharp and narrow? This means that most of the groups have similar statistical behavior, so you could consider not splitting them. Are there two distinct peaks in the histograms? That signals two obvious characteristics in your groups. It's worth investigating more.	View histograms for the three supported distribution types of Normal, Exponential, and GaussianKDE. Review these results for statistical behavior needing further investigation.

Button labels

Follow these guidelines when writing button labels:

• Write concise button text. Aim for 1 or 2 words and no more than 4 words.
• Avoid using "Yes" or "No". Instead, write a clear call to action. Be specific so that the user is sure of what action happens after they select the button.
• If the button text requires more than one word, start the text with a verb.
• Use a precise verb to describe the action. For example, use "Add" when using an existing object in a new context, and use "Create" when making a new object from scratch.
• Use sentence-style capitalization and capitalize the first word and proper nouns only.
• Avoid articles such as "a", "an", or "the".
• Don't use punctuation such as periods or exclamation marks.

The following table shows correct and incorrect examples of button labels:

Correct	Incorrect
Cancel	No
Save	Yes
Create dashboard	Create Dashboard
Create table view	Create a table view
Continue to tour	Continue to the tour!

Empty state text

An empty state is a screen in the product UI that will eventually have content on it after the user populates it. Empty state UI text is the information that a user sees instead of a blank screen.

Follow these guidelines when writing empty state text:

• Explain why the page is empty and what the user can do next.
• Write text that guides the user to the next step.
• Include a button or a link to the next step.

The following image is an example of empty state text:

Error or warning messages

When writing a user-facing error or warning message, clearly state the problem and what the user can do to resolve it. For field validation error messages, it's okay to state the action to resolve the problem without explicitly stating the problem since cues in the UI, like the positioning of the error next to the field, identify the problem.

When writing an error message, use these guidelines:

• Use complete sentences with end punctuation.
• Don't use "please".
• Don't place the blame on the user for making a mistake.

The following examples of error messages are revised for clarity and provide an action that the user can take:

Original message	Rewritten message
You entered the wrong username.	Username not found. Verify that the username is correct and try again.
Your email address hasn't been entered.	Enter your email address.
Max number of concurrent searches reached.	The maximum number of concurrent searches has been reached. Decrease the number of concurrent searches or increase search concurrency limits in limits.conf.
WARN DistributedPeerManager - Unable to distribute to peer named xxxx at uri http://xxxx:8089 because peer has status = "Authentication Failed".	WARN DistributedPeerManager - Unable to distribute to peer named xxxx at http://xxxx:8089 because authentication failed. Make sure adequate system resources are available on the target server.
Max search jobs encountered.	The maximum number of search jobs has been reached. To reduce the number of search jobs, go to Job Inspector and delete unneeded jobs.