Elastic UI

Writing guidelines

You can have the most beautiful UI, but without consistent, easy-to-understand text, you haven’t built the best user experience.

Principles

Clear and concise

Get straight to the point—in a way that your users understand. Make every word contribute to meaning.

Consistent

Use the same terminology to mean the same thing. Make sure spelling, capitalization, punctuation, labels, and use of abbreviations are all consistent.

Conversational

Write as a professional in the field would talk—not as a professor lecturing students. Use words that the user would use.

Capitalization

Sentence case for almost all text

This includes buttons, menus, and titles. In sentence case, only the first word and proper names are capped.

Create index patterns
Do. Sentence case makes titles easier to read.
Create Index Patterns
Don't. Title case can feel more cluttered.
Do. Sentence case is friendlier in button labels.
Don't. Title case looks too formal.

Title case for feature titles

Titles and tabs for specific features should capitalize all words in the name of the feature.

Do. Title case in tabs and titles for names of features.
Don't. Features are proper names, not sentences.

Writing style

Write in active voice

Active voice puts the focus on who or what is performing the action and makes the sentence easier to understand.

The Elasticsearch Query DSL builds filters.

Do. Writing in active voice puts the subject first.

Filters are built using the Elasticsearch Query DSL.

Don't. With passive voice, it's harder to tell who's doing what.

Keep it short and snappy

Identify the most important information and say it concisely. Don't repeat what's already been said or state the obvious. Omit common introductory phrases.

Edit saved objects

Do. Keep it short.

Edit saved objects

From here, you can edit saved objects. To get started, follow these steps.

Don't. Repeat what's already been said or state the obvious.

Configure at least one index pattern.

Do. Get straight to the point.

In order to use Kibana, you must configure at least one index pattern.

Don't. Use unnecessary introductory phrases.

No active shard records for this cluster.

Do. Ensure all words contribute to meaning.

There are currently no active shard records for this cluster.

Don't. Start a sentence with "There are" or "There is."

Addressing the user

In most cases, address users as "you"

It's friendly and engages the user directly.

You must configure TLS to apply a Platinum license.

Do. Converse directly with the user using "you" and "your."

Configuring TLS will be required to apply a Platinum license.

Don't. Avoid the user. It creates awkward phrasing such as "will be required."

In some cases, "we" and "our" are appropriate

The use of "we" is appropriate for situations where you're taking an action for the user or making a suggestion. It's best reserved for onboarding and empty states.

We noticed that you don't have any data in your cluster. Try our sample data and dashboards or jump in with your own data.

Do. Use "we" when taking an action on behalf of the user.

Let's create a database

Let's create a visualization

...

Don't. Overuse "us." It can become annoying.

Less common are "I" and "my"

Use first person when you want to give the user ownership of an action.

Explore on my own

Do. Use "my" in buttons and links to give users ownership.

I agree to follow the terms of service

Do. Use "I" in agreement statements.

Punctuation

Don't use unneccessary punctuation

Although punctuation can help clarify meaning, it can also clutter the UI. Don't add a colon after a label, an ellipsis (...) at the end of an action, an (s) at the end of a noun, or add parentheses (()).

Separate multiple names with a comma
Do. Use an "s" or "es" to show plural.
Separate multiple names with a comma (other characters are unsupported).
Don't. Use (s), a colon after labels, or parenthetical statements.
Do. Remove the ellipsis from Search fields.
Do. Use an ellipsis for truncated text or situations that require waiting.

Know when to use the ending period

Use periods at the end of complete sentences in body text. These are typically supplemental explanations and instructions. Avoid periods in titles, headings, and sentence fragments.

Number must be between 1 and 5.
Do. Use periods after sentences in help text.
Index management
Update your Elasticsearch indices individually or in bulk
Don't. Use a lead-in sentence without an ending period. It looks wrong.

Use contractions

Use contractions if they make your text flow more naturally, such as "didn't" instead of "did not" and "can't" instead of "cannot."

Didn't find what you were looking for?

Do. Use contractions if they make the text easier to read.

Did not find what you were looking for?

Don't. Without the contraction, this text sounds stilted.

Limit the use of exclamation points

Showing excitement is best reserved for greetings and encouraging messages. Don't use more than one exclamation point per page.

This dashboard is empty. Fill it up!

Do. Use exclamations for encouragement, but use sparingly.

Couldn't find any Elasticsearch data!

Don't. Use exclamation points in error messages.

Messages

Summarize the message in the title

Don't start with the words error, warning, and confirm, or jargon such as oops and uh-oh. A title-only message is ok.

This dashboard is empty

To add a visualization, click Add in the menu bar. No visualizations yet? Go to Visualize to create one.

Do. Provide a title that is meaningful to the user.
Uh-oh!

This dashboard is empty. To add a visualization, click Add in the menu bar. No visualizations yet? Go to the Visualize app to create one.

Don't. Use uh-oh, oops, or other meaningless text in the title.

Include critical information first

Tell the user the most important information first, and less critical information second.

You need to increase your subscription limit. Please contact support.

Do. Prioritize the contents of the message.

Contact support because you need to increase your subscription limit.

Don't. Hide important information at the end.

No data sources. Go to Management to define an index pattern.

Do. State what went wrong, followed by a clear course of action.

Oops, no data sources.

Don't. Leave the user guessing about next steps.

Avoid using "Are you sure"

Your text is more direct without it.

Delete this report?
Do. Keep titles as concise as possible.
Are you sure you want to delete this report?
Don't. Pad the title with empty words—it increases reading time.

Avoid using "please"

In most cases, "please" is unnecessary. Exceptions are situations where the user must wait or do something inconvenient. Or, if the text sounds too abrupt without it.

Save your work before generating a report.

Do. Omit "please" in longer instructions.

Please save your work before generating a report.

Don't. Use "please" when a pleasantry is not needed.

Your session has expired. Please log in again.

Do. Use "please" only when it feels natural and makes short text less abrupt.

Please wait.

Do. Use "please" when asking the user to wait.

Use 1 to 2 simple, short sentences

Don’t force the user to read long blocks of text. Write for scanning. Link to documentation.

Must be least 8 characters and include upper and lower case letters, numbers, and symbols such as !@#$%.
Do. Write for scanning.
Passwords must be at least 8 characters long. Good passwords contain either a combination of upper and lowercase letters or a combination of letters with one digit. Strong passwords contain either a combination of letters and more than one digit or special characters.
Don't. Write long blocks of text.

Avoid the urge to explain everything

Not every task requires an explanation nor does every field require placeholder text.

A template defines the settings, mappings, and aliases to apply when you create an index.
Do. Explain new or difficult concepts.
Please enter your email address.
Don't. Provide explanations for common actions.

Labels

Convey the purpose of the component

Avoid long labels, but don't sacrifice clarity. If needed, put additional information in help text and tooltips.

Do. Use labels that say what the component does.
Don't. Use generic labels.

Label buttons with their action

Don't use Yes or OK when you can use a verb phrase instead.

Remove this index pattern?
Do. Use a verb + noun for a button label.
Remove this index pattern?
Don't. Use vague labels, such as Yes and OK.

Be careful with humor

Your text can be fun as long as it fits the experience—and doesn't get in the user's way. Clever text can become annoying when used for frequently performed tasks. Situations where the user might lose data or otherwise be frustrated are also not appropriate for humor.

Odd, exciting, and scary trends and anomalies in your Elasticsearch data

Do. Make it fun only if it fits the experience.
No results found

Unfortunately, I could not find any results matching your search. I tried really hard. I looked all over the place and frankly, I just couldn't find anything good. Help me, help you.

Don't. Be clever with a serious message.

Verifying your text

Work with a writer

A writer can help determine where you need text and what it should say.

Read your text out loud

Word flow has a natural feel to it. Read your text out loud, make changes, and then repeat until the flow of your text feels natural.

Use spell check

Run your text through a spelling and grammar checker.