Writing
You can have the most beautiful UI, but without consistent, easy-to-understand text, you haven’t built the best user experience.
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
In sentence case, only the first word and proper names are capped. In title case, the first letter of each word, except for articles, conjuctions, and prepositions, is capitalized.
Do: Use sentence case in buttons, menus, titles, and tabs.
Save your session and return to it later.
Do: Use sentence case for modal and page elements.
Do: Data streams, index templates, and enrich polices are features and use sentence case.
Suppress rule notifications for scheduled periods of time.
Do: Maintenance windows is a feature and uses sentence case.
Title case for proper nouns
Proper nouns include product names, solutions, apps, feature tiers, and subscription levels.
- Welcome to Elastic Observability
- Elastic APM
- You have chosen Security Analytics Essentials.
- This feature is available for Gold subscriptions and higher.
Do: Product and solution names are always capitalized. Same goes for feature tiers and subscription levels.
Building a dashboard?
Create content directly from our Dashboard app using our new integrated workflow. Learn more(external, opens in a new tab or window)
Do: App names are also capitalized, as seen in Dashboard app in this example. When referring to building a dashboard, the term is capitalized. In another example, the Machine Learning app is upper case, but the machine learning feature is lower case.
For more information, view the Elastic name guidelines.
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."
Do: Avoid unneeded words in button labels.
Don't: Use "create a new" or include articles in button labels.
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
Don't: Use "I" in agreement statements.
Punctuation
Don't use unnecessary 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 ().
Do: Use an "s" or "es" to show plural.
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 help text and complete sentences in body text. These are typically supplemental explanations and instructions. Avoid periods in titles and headings.
Do: Use periods at the end of help text.
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.
Do: Keep titles as concise as possible.
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.
Do: Write for scanning.
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.
Do: Explain new or difficult concepts.
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.
Do: Use a verb + noun for a button label.
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.
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.
Specific component guidelines
Find specific guidelines and examples by checking component details.
Need some more writing examples? Check out the Examples page.