UI text style guidelines
These guidelines provide a quick reference for anyone who writes user interface text at Splunk.
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, punctuation, and more:
|Usage dictionary||Usage dictionary|
|Product terminology||Splunk product terminology|
|Splunk-specific terminology definitions||Splexicon|
|Punctuation||Punctuation and symbols|
|Voice and tone||Tone|
|Unbiased language||Write unbiased documentation|
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|
When writing single, short, descriptive phrases in UI text, don't use a period at the end. If an item requires more than one phrase, 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.
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."
Use numerals for numbers that appear in the UI, including 0 through 9. Try to avoid starting a sentence with a numeral.
The guidelines for writing numbers in UI text differ from the guidelines for writing numbers in Splunk documentation. See Using numbers in text for Splunk documentation guidelines.
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:
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.
|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.||Click here to view and manage your table views.|
|Manage team schedule.||Click here to manage team schedule.|
|If you're interested in monitoring infrastructure, start by installing the Splunk Wizbang product or other integrations.|
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.
|View on Splunkbase||Download the app.|
|View AWS docs||Review the AWS documentation.|
|Download Ansible||Ensure that you have Ansible 2.9+ installed.|
A Learn more link is a type of standalone link. Use a Learn more link to link to official 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.
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.
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:
The following table shows correct and incorrect examples of Learn more links:
|To learn more about the Splunk Wizbang product, read the documentation.|
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 next to the UI element so it's always visible. Don't include interactive elements such as links or buttons in tooltips.
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.
- 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".
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. 1 hour ensures 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.|
Error or warning messages
When writing a user-facing error or warning message, focus on error recognition and recovery. Clearly state the problem, the cause, and what the customer can do to remediate or recover. Use complete sentences with end punctuation. Don't use "please".
The following examples of error messages are revised for clarity and provide an action that the user can take:
|Original message||Rewritten message|
|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.|
|Could not load/save the object. May need to check user settings for roles and permissions. Details: An internal error has occurred.||The glass table can't be saved because it has the same name as the glass table it was cloned from. Change the name of the cloned glass table.|
Follow these guidelines when writing button labels:
- Write concise button text. Aim for one or two words and no more than four words.
- If the button text requires more than one word, start the text with a verb.
- Use precise language 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 (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:
|Create dashboard||Create Dashboard|
|Create table view||Create a table view|
|Continue to tour||Continue to the tour!|
Manual names, topic titles, and section headings
Best practices for including videos
This documentation applies to the following versions of Splunk® Style Guide: current