Splunk® Style Guide

Splunk Style Guide

Acrobat logo Download manual as PDF


Acrobat logo Download topic as PDF

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:

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 Tone

Use plain language
Be active and present
Write in indicative or imperative mood

Unbiased language Write unbiased documentation

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

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.

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

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.

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

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

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 iconexternal 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.
Correct Incorrect
View on Splunkbaseexternal link icon Download the app.
View AWS docs external link icon Review the AWS documentation.
Download Ansibleexternal link icon 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 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: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:

Learn more link preceded by a sentence that provides context for the link.

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

Correct Incorrect
Learn more link Learn more link without icon
  Learn more link with period
  Learn more link miscapitalized
  Learn more in a hyperlinked sentence.
  Learn more link in a sentence
  To learn more about the Splunk Wizbang product, read the documentation.

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


Button labels

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:

Correct Incorrect
Create dashboard Create Dashboard
Create table view Create a table view
Continue to tour Continue to the tour!
Last modified on 25 January, 2023
PREVIOUS
Manual names, topic titles, and section headings
  NEXT
Best practices for including videos

This documentation applies to the following versions of Splunk® Style Guide: current


Was this documentation topic helpful?


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