Splunk Style Guide

Splunk Style Guide

Download manual as PDF

Download topic as PDF

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:

Topic Link
Usage dictionary Usage dictionary
Product terminology Splunk product terminology
Splunk-specific terminology definitions Splexicon
Abbreviations Abbreviations
Acronyms Acronyms
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
  • Tooltips
  • Banners
  • Drop-down content

Terminal punctuation

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.

Learn more links

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: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:

Learn more icon

Tooltips

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.
Last modified on 11 February, 2020
PREVIOUS
Documenting third-party products
  NEXT
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


Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

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