UI text style guidelines

These guidelines provide a quick reference for anyone who writes user interface text at Drucare.

Much of the guidance for Drucare 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 Drucare 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 Drucare product terminology
Drucare-specific terminology definitions Drulexicon
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 of UI text

Use the following capitalization guidelines for text in Drucare product UIs. See the Drulexicon for the correct capitalization of Drucare 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
  • System-generated chart labels 

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-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 Drucare documentation. See Using numbers in text for Drucare documentation guidelines.

Learn more links

Use a Learn more link to link to documentation from a page or dialog box in the UI. 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.

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.
Was this article helpful to you? No Yes

How can we help?