UI text style guidelines
These guidelines provide a quick reference for anyone who writes UI 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 UI 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||Voice and tone|
Capitalization of UI text
Use the following capitalization guidelines for text in Splunk product UIs. See the Splexicon for the correct capitalization of Splunk terms. Don't use capitalization for emphasis.
What is headline-style capitalization?
In headline-style capitalization, capitalize the first and last words, nouns, pronouns, verbs, adjectives, adverbs, and subordinating conjunctions (if, because, as, that, and so on). Don't capitalize articles (a, an, the), coordinating conjunctions (and, but, or, nor), the "to" in an infinitive, and prepositions (with, to, for, in, from).
For hyphenated words, capitalize the first element and the subsequent elements unless they are articles, prepositions, and coordinating conjunctions. The following are examples:
- Cross-Selling Opportunities
- The Command-Line Interface
When to use headline-style capitalization
Use headline-style capitalization for names, titles, or headings. For example, use headline style for the following elements:
- Dashboard panel titles
- Dashboard section titles
- Page titles
- Dialog box titles
- Wizard titles
- Column headers in tables
- Button text
What is sentence-style capitalization?
In sentence-style capitalization, capitalize the first word and all proper nouns, such as product names or proper feature names.
When to use sentence-style capitalization
Use sentence-style capitalization for anything that reads as, or is similar to, a sentence. For example, use sentence-style capitalization for the following elements:
- Field labels
- Switch labels
- Field descriptions
- Descriptive or explanatory text
- Error messages
- Drop-down content
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. However, if it isn't possible to rewrite the full sentences into fragments, use terminal punctuation for all of the text.
For more punctuation guidelines, see Punctuation and symbols.
Use a Learn more link to link to documentation about a UI page. The format is as follows:
- Capitalize the first word only. For example: Learn more.
- Always place the Learn more link after related descriptive or explanatory text.
- Never refer to a specific doc manual in text that precedes the Learn more link.
- Don't add any text after the Learn more link.
- Don't use punctuation.
- 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:
Use tooltips to 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.
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. Aim for fewer than 150 characters.
- If the UI element requires a more lengthy explanation, put this explanation in the documentation.
- Use sentence-style capitalization for complete sentences.
- 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|
|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 cannot be saved because it has the same name as the glass table from which it was cloned. Change the name of the cloned glass table.|
Documenting third-party products
Where to look if the Splunk Style Guide doesn't answer your question
This documentation applies to the following versions of Splunk Style Guide: current