diff --git a/packages/website/docs/content/accessibility.mdx b/packages/website/docs/content/accessibility.mdx new file mode 100644 index 00000000000..50fb7c67518 --- /dev/null +++ b/packages/website/docs/content/accessibility.mdx @@ -0,0 +1,84 @@ +--- +id: content_accessibility +slug: content-accessibility +--- + +# Accessibility + +This page shares common tips and tricks for writing accessible UI copy. It is not exhaustive and does not replace the official +[WCAG 2.0 guidelines](https://www.w3.org/TR/2008/REC-WCAG20-20081211/#guidelines). + + +Writing accessible UI copy is only one part of improving web accessibility. Check the [EUI documentation](https://eui.elastic.co/#/guidelines/accessibility) for more accessibility guidelines. + + +## What is accessible content and why does it matter + +**Accessibility** for content means making sure that the content can be consumed properly, independently of how users choose or have to interact with it. + +Our users and readers are diverse, with different abilities, and disabilities. +They also interact with our content in different ways: screen readers, mobile devices, Braille, and so on. The list is long, and always evolving. + +As content authors, it is our responsibility to provide them with [perceivable, operable, understandable, and robust content](https://www.w3.org/TR/UNDERSTANDING-WCAG20/intro.html#introduction-fourprincs-head). + +## Guidelines + +✔️ **Make your content scannable.** A clear structure and meaningful words tell users if the feature or flow is relevant to them within seconds. + +✔️ **Add alt text for all images, icons and media files.** Screen readers, Braille output devices, and search engines love concise, accurate alt text that describe what cannot always be displayed, viewed or heard on screen. + + +| Inaccessible | | Accessible | +| --------------------- | --- | ------------------------- | +| Image of in progress rule creation form. | → | User is setting up a new threshold rule. | +| Logs integrations | → | Integrations that let you to ingest logs. | + + +✔️ **Use plain language.** Clear, concise UI copy helps users perform tasks. Jargon and complex sentences can confuse or slow them down. Helpful and detailed plain language guidance can be found on the [plainlanguage.gov](https://www.plainlanguage.gov/guidelines/) website. + + +| Inaccessible | | Accessible | +| --------------------- | --- | ------------------------- | +| Update the sourcerer selection to be the default detections data view. | → | Choose the default Security data view. | +| **Cancel update rule?** You will lose changes to the rule. | → | **Discard rule changes?** Select **Discard** to reject these changes. | + + +✔️ **Use meaningful link text.** Descriptive text instead of "click here" or "read more" helps users understand what to expect when they open the link. Screen readers jump between links by generating a list of them, and spell out URLs. + + +| Inaccessible | | Accessible | +| --------------------- | --- | ------------------------- | +| Click here for more information. | → | Learn more about indices. | +| Create a query. Learn more. | → | Learn how to create an ES\|QL query. | + + +✔️ **Use device agnostic language.** Users can access content and products in many ways. We do not know if they use a mouse, a keyboard, a tablet, and so on. + + +| Inaccessible | | Accessible | +| --------------------- | --- | ------------------------- | +| Type in your username and password. | → | Enter your username and password. | +| Select a time range for the Alerts table. | → | Choose a time range for the Alerts table. | + + +✔️ **Avoid directional language.** Do not use above, below, left, right, and so on. All these terms assume that UI layouts never vary, that users can actually see the UI, and that they see it the way you think they do. Users might have disabilities or impairments that affect how they understand the UI. + + +| Inaccessible | | Accessible | +| --------------------- | --- | ------------------------- | +| Complete the form below. | → | Complete the following form. | +| Import values from a file by clicking the **Import values** button under the table. | → | Select **Import file** to import values from supported file types. | + + +## Words to avoid + +Avoid the following words. Use the suggestions instead. + +| Avoid | | Use instead | +| --------------------- | --- | ------------------------- | +| Click, tap | → | Select, choose | +| Above, over | → | Preceding, previous | +| Below, under | → | Following, further, later | +| See | → | Check, refer to | +| Hear (hear about...) | → | Learn | +| Type | → | Enter | \ No newline at end of file diff --git a/packages/website/docs/content/adapt-tone.mdx b/packages/website/docs/content/adapt-tone.mdx new file mode 100644 index 00000000000..8538f3bb0c0 --- /dev/null +++ b/packages/website/docs/content/adapt-tone.mdx @@ -0,0 +1,183 @@ +--- +id: content_tone +slug: content-tone +sidebar_position: 20 +--- + +# Tones + +Adapt the way you write to each situation users can face. + + Our products and solutions are very technical, data-oriented, and they're used globally by people from different cultures, abilities, and personalities. + These considerations, amongst others, limit the spectrum of tones we use to some extent, but not entirely. + + During the users' journey with Elastic, there are times for excitement and discovery, but also times for help, support, and empathy. + + + ## Stimulating + +**Attributes** + + We're proud to show new and cool stuff. Be: + + - Motivational + - Excited + - Enthusiastic + + When using this tone, you may: + - Use exclamation marks, but sparingly. + - Take time to help the user understand how this feature benefits them. + - Use visuals to support your text. + +**Cases** + + Although it can be very visible because of the way it's written and the UI elements it shows in, the **stimulating** tone is used **quite rarely** overall. + + We use it when we want to show new things to users, especially in: + + - Product tours + - New feature announcements + +## Friendly + +**Attributes** + + All's fine, we'll help you find your way. Be: + + - Calm + - Positive + - Confident + + When using this tone, you may: + - Use more casual terminology. + - Explain what's missing or what's happening. + - Provide actions or clearly state when there's no action needed. + + +**Cases** + + The **friendly** tone is used **sparingly** overall and usually blends in the UI at different moments of the users' journey. + + We use it when orienting users in doing their next action or learning different things they could do, especially in: + + **UI** + - Empty states (no item created or no matching results) + - Loading and waiting states + - Tips + - Success messages + - Welcome emails (signup & trial) + + **Documentation** + - Quick starts + - Tutorials + +## Informational + +**Attributes** + + E=MC². Be: + + - Direct + - Straight to the point + - Neutral + + When using this tone: + - Use a minimum of words. + - Write for scanning and help users quickly locate what matters to them. + - Use action verbs to: + - Label selection controls. + - Describe what settings do or what to do with a setting. + - Use clear nouns for + - menus, form field names + + +**Cases** + + The **informational** tone is the **most used** one. It is everywhere in the UI, and sometimes seems so normal that we forget about it. Yet, it is very important! + + We use it for naming and describing things: + + - Menus, titles, setting names, hint text, placeholders, introductions, and descriptions + - In-product assistance (tooltips, help popovers, guided setups) + - Information callouts + - Confirmation modals + - Calls to action (buttons and links) + - Event logs + + **Documentation** + - Reference content + - Concepts + - How-tos + - Troubleshooting + +## Empathetic + +**Attributes** + + Something might be wrong and requires attention. Let us help you. Be: + + - Reassuring + - Professional + - Precise + + When using this tone, you may: + - Be more action-oriented than usual to offer direct paths to users. + + +**Cases** + + The **empathetic** tone is used **sparingly** overall and is usually shown in places that draw the user's attention. + + We use it when notifying users of things that are not immediately critical but still require attention, especially in: + + - Warnings and cautions + - Upgrade and deprecation notices + +## Supportive + +**Attributes** + + Something is definitely wrong. Here's why, and how to fix it. Be: + + - Serious + - Concerned + - Urgent + + When using this tone, you may: + - Focus on what went wrong. Don't be apologetic. + - Help users learn how something happened, how to prevent it, how to fix it. + - Provide clear actions, or clearly state it if there's no action needed. + + + +**Cases** + + The **supportive** tone is used **sparingly**. It usually becomes visible in forms that draw the user's attention, for example, through callouts or notifications. + + We use it when the immediate attention of the user is required, especially in: + + - Errors + - Licensing or billing-related content + - Vulnerability and remediation content + +## Stern + +**Attributes** + + We don't advise this action, but you're the master of your destiny. Be: + + - Deterring + - Heavy with caution + - Advisory + + When using this tone, you may: + - Use stronger words that highlight possible negative effects. + - Format the content in a way that make the risks stand out. + +**Cases** + + The **stern** tone is **rarely** used. Reserve it for very specific cases, and for advanced or administrative features. + + We use it when insisting on the high risks an action could pose, especially in: + + - Danger type of warnings \ No newline at end of file diff --git a/packages/website/docs/content/inclusivity.mdx b/packages/website/docs/content/inclusivity.mdx new file mode 100644 index 00000000000..8a739f08da6 --- /dev/null +++ b/packages/website/docs/content/inclusivity.mdx @@ -0,0 +1,106 @@ +--- +id: content_inclusivity +slug: content-inclusivity +--- + +# Inclusivity + +This page provides guidelines for writing inclusive UI copy for product content but it's not exhaustive. + +## What is inclusive content and why does it matter + +**Inclusivity** for content means making sure that the content we serve reflects the diversity of our community, respects it, and promotes positive change. + + +## Guidelines + +### Write for an international audience + +Our products use American English (en_US) as a standard for written content. +Yet they are used, read by persons all around the globe, for whom English is not always their primary language. +Our content must take that into account. + +✔️ **Aim for simplicity.** Indeed, we are a technical company, writing for + technically-savvy users. However, it benefits everyone if we try to keep our writing as simple as possible. + + * **Short sentences** - They leave less space for interpretation. They are easier to scan, read, and translate. + + * **Plain language** - Use active voice, present tense, using examples, and so on. + Some of these guidelines might already look familiar. Several countries have + [plain language initiatives](https://www.plainlanguage.gov/guidelines/) to + promote clearer communication. Do your + best to embrace these guidelines and focus on the message. + + * **Negation** - It is easier to say what something IS + versus what it is NOT. When you add a negative construction, it takes the + reader longer to parse the meaning of the phrase. For example, instead of saying "You cannot access the content without signing up", say "Sign up to access the content." + + * **Words with multiple meanings** - + Don't skip helper words if they make the sentence clearer and easier to read. In UI copy, we try to be as literal and unambiguous as possible to ensure that it can be easily consumed by our users from around the globe. One way to achieve that is to choose words that have fewer meanings, especially when a word's intended meaning is not its primary meaning. + +✔️ **Be aware of differences and diversity in content and examples.** +Different people are used to different names, currencies, date and time formats, different units of measurement (like for temperature, distance, speed), and so much more. +* Avoid ambiguous values, like `04/05/06` for a date. Is it May 4 or April 5, and which year? `11/17/1987` leaves less room for interpretation if the exact format is not specified nearby. +* If there is no obvious example standard (RFC) to follow, try to be diverse to represent our audience. + +✔️ **Avoid idioms or expressions that are not commonly known, a.k.a regionalisms.** + +In our Elastic documentation we aim for a fun, friendly, and sometimes quirky +tone. To achieve that, it can help to use informal, playful language. However, we also have to be careful that our text is as inclusive as possible, so we try to avoid expressions that might be unknown or opaque for some users. Here are a few examples of what to avoid: + +* Idioms (for example, _It's a piece of cake_ or _So far so good_) +* Regional expressions (for example, _G'day!_, _Y'all_, or _eh_) +* Sports expressions (for example, _touched base_ or _threw a curve ball_) +* Pop culture references (for example, _Elvis has left the building_ or _Same bat-time, same bat-channel_) + +We're all pretty good at avoiding these, but there's one problematic type of +expression that sometimes shows up in UI copy. Latin terms and +abbreviations are a common source of confusion, particularly for people whose +first language does not have Latin roots. + +Here are some terms to avoid and suggested alternatives: + +| Avoid | | Use instead | +--- | --- | --- +| _e.g._ (exempli gratia) | → | _for example_ | +| _etc._ (et cetera) | → | _and more_ or _and so on_ | +| _i.e._ (id est) | → | _that is_ | +| _via_ | → | _by way of_, _by means of_, or _through_ | + +✔️ **Aim for readability.** Tools like the [Hemingway App](https://hemingwayapp.com/) can help you make content simpler. Be conversational, but prioritize clarity. + +### Use gender-neutral language + +Writing gender-neutral mainly consists in avoiding gender bias and word choices implying that one gender is the norm. + +✔️ **Pronouns.** In the UI, this can be avoided by addressing users directly. +When it's not possible, use *they*/*their*, even for singular. There's more than one gender, and it's not binary either. + +✔️ **Biased words and expressions.** Guys, mankind, policeman... Words that we're all used to hear and use. But the default is not male. +Most expressions and words that perpetuate this bias (that exists in many cultures and languages!) can be replaced with neutral alternatives or synonyms: Folks, humanity, police officer... + +### Avoid violent, offensive, ableist terminology + +Earlier in this page, we discussed avoiding ambiguous terms, especially when a word's intended meaning is +not its primary meaning. Other types of words and phrases best avoided are: + +* buzzwords (_incentivize_, _synergies_) +* superhero terms (_rockstar_, _wizard_, _ninja_) +* violent imagery (_crush the competition_) +* non-specific superlatives (_unrivaled_, _unparalleled_, _world class_) + +Some words have nuances that fall into the above categories, which may cause +them to be misinterpreted. Here are some alternatives: + +| Avoid | | Use instead | +--- | --- | --- +| Abort | → | _stop_, _cancel_, or _end_ | +| Boot | → | _start_ or _run_ | +| Execute | → | _run_ or _complete_ | +| Hack (noun) | → | _tip_ or _workaround_ | +| Hack (verb) | → | _configure_ or _modify_ | +| Hit (verb) | → | _click_ or _press_ | +| Hit (noun) | → | _visits_ (as in _website visits_) | +| Invalid | → | _not valid_ or _incorrect_ | +| Kill | → | _cancel_ or _stop_ | +| Terminate | → | _stop_ or _exit_ | \ No newline at end of file diff --git a/packages/website/docs/content/language.mdx b/packages/website/docs/content/language.mdx new file mode 100644 index 00000000000..5d303058ef8 --- /dev/null +++ b/packages/website/docs/content/language.mdx @@ -0,0 +1,109 @@ +--- +id: language +slug: language +sidebar_position: 30 +--- + +# Language + +Guidelines for using consistent spelling and terminology in the UI. + +## Spelling + +Use American English when writing UI copy. American English is a version of the English language used in the United States. It's sometimes called United States English or U.S. English. + +Certain words are spelled differently in American English and British English. You'll find some of these key spelling differences in the following sections. + +### Verbs that end with 'ize' or 'yze' + +In American English, verbs that end with 'ize' usually end with 'ise' in British English. Similarly, verbs that end with 'yze' in American English usually end with 'yse' in British English. + +| American English | British English | +| ------------- |:-------------:| +| organize | organise | +| authorize | authorise | +| analyze | analyse | + +### Nouns that end with 'or' + +In American English, nouns that end with 'or' usually end with 'our' in British English. + +| American English | British English | +| ------------- |:-------------:| +| flavor | flavour | +| color | colour | +| behavior | behaviour | + +### Nouns that end with 'ense' + +In American English, nouns that end with 'ense' usually end with 'ence' in British English. + +| American English | British English | +| ------------- |:-------------:| +| license | licence | +| defense | defence | +| pretense | pretence | + +### Nouns that end with 'og' + +In American English, nouns that end with 'og' usually end with 'ogue' in British English. + +| American English | British English | +| ------------- |:-------------:| +| dialog | dialogue | +| catalog | catalogue | +| epilog | epilogue | + +## Case + +Use **sentence case** by default. This goes for navigation menus, titles and headers, buttons, and so on. + +- **Do:** Developer tools. Data streams. Index templates. Save session. +- **Don't:** Developer Tools. Delete Deployment? Run Search. + +The only exceptions are proper nouns and [branded terms](https://brand.elastic.co/302f66895/p/194a3b-writing-style-guide/t/159934) like solution and application names. + +- **Do:** Elastic Observability. Go to the Discover app. Upgrade to Platinium. +- **Don't:** Select gold subscription. Open the synthetics app. + +Note that some names don't need to be capitalized when they're used as common names. For example, **Elastic Cloud Serverless** and **our serverless architecture** are both correct. + +## Punctuation + +### Ellipsis + +Only use ellipsis for truncated text or situations that require the user to wait. + +- **Do:** Page loading... +- **Don't:** Elastic offers many capabilities such as dashboards, machine learning, synthetics monitoring... + +### Exclamation mark + +Avoid exclamation marks in most cases. A single exclamation mark when sharing exciting news may be appropriate. + +### Oxford comma + +Use the Oxford comma before the final item in a list. + +- **Do:** Elastic's solutions are Elasticsearch, Observability, and Security +- **Don't:** Elastic's solutions are Elasticsearch, Observability and Security + +### Periods (full stops) + +Use periods with: + +* description text +* messages +* notifications +* list items that are complete sentences + +Don't use periods with: + +* headers +* titles +* placeholders +* list items that are incomplete sentences + +## Vocabulary + +Check [Word choice](./word-choice.mdx) for guidance on specific terms to use or to avoid. diff --git a/packages/website/docs/content/overview.mdx b/packages/website/docs/content/overview.mdx new file mode 100644 index 00000000000..8d02b09ea75 --- /dev/null +++ b/packages/website/docs/content/overview.mdx @@ -0,0 +1,21 @@ +--- +id: content_overview +slug: writing-guidelines +sidebar_position: 1 +--- + +# Content + +Our content guidelines cover the main principles we follow for crafting consistent, clear, and concise copy across Elastic products: + +- [Voice and writing style](./style.mdx) +- [Tones](./adapt-tone.mdx) +- [Language](./language.mdx) +- [Accessibility](./accessibility.mdx) +- [Inclusivity](inclusivity.mdx) +- [Word choice](./word-choice.mdx) + +Some more specific guidelines and best practices apply in certain situations or for certain components: + +- [Patterns](../patterns/) +- [Components](../02_components/) \ No newline at end of file diff --git a/packages/website/docs/content/style.mdx b/packages/website/docs/content/style.mdx new file mode 100644 index 00000000000..72b360b922b --- /dev/null +++ b/packages/website/docs/content/style.mdx @@ -0,0 +1,43 @@ +--- +id: writing_style +slug: writing-style +sidebar_position: 10 +--- + +# Voice and writing style + +Our **Voice** represents the personality we want to convey through the UI copy in our products. +The following principles define the fundations of our voice. + +### Conversational +Real people, talking to real people. + +| ✔️ Be... | How? | +|--------------------|-----------------------------------------------------------------------------| +| User-focused | Address users directly. Don't abuse possessive markers like "yours".[1] | +| Plainspoken | Be conversational, yet professional. Write close to how you'd talk. Use contractions and active voice. | +| Inclusive | Write for all audiences. Our users are from everywhere. Don't use terms that might discriminate or offend and avoid complex language for non-native English speakers such as phrasal verbs. | +| Empathetic | Write what matters to users. Use words that you normally use. | + +> [1] Sometimes, we give the user full ownership of an action. In that case, it's acceptable to use "I" and "my". For example, for a legal agreement checkbox "I agree to follow the terms of service". We can also use "We" when talking about actions Elastic takes for users. + +### Practical +Get the user's job done. + +| ✔️ Be... | How? | +|-------------|-----------------------------------------------------------------------------------------| +| Timely | Help users when it's needed. Not everything is critical to describe in more details or at once. Make information discovery progress at the same pace as the user. | +| Informative | Ensure all content serves a purpose and is not just decoration. Be straight to the point. It's not mandatory to have help text and descriptions for everything.| +| Precise | Avoid using verbs or determiners alone without a noun in buttons and action menus to add clarity. For example, prefer "Save dashboard" over "Save". Or "this setting" over "this".| +| Succinct | Shorten the content to something meaningful and scannable, without sacrificing clarity. Delete unnecessary or vague wording like most adverbs. | + + +### Authentic +Inspire trust. + +| ✔️ Be... | How? | +|-------------|------------------------------------------------------------------------------------| +| Optimistic | Help users progress and succeed with what they are doing right now. Do not blame them in case of errors and instead let them know what to do and encourage actions. | +| Confident | Encourage best practices but let users choose their path. Provide them with just enough information to help them make informed decisions. | +| Transparent | Help users connect the dots without jargon or vague statements. Provide values or realistic ranges to set the right expectations. For example "This operation can take up to 5 minutes" instead of "Wait a few minutes while we get you set up". | + diff --git a/packages/website/docs/content/word-choice.mdx b/packages/website/docs/content/word-choice.mdx new file mode 100644 index 00000000000..299cd628fdd --- /dev/null +++ b/packages/website/docs/content/word-choice.mdx @@ -0,0 +1,120 @@ +--- +id: word_choice +slug: words +--- + +# Word choice + +Find the right term to use in your UI copy. + +## Use these preferred words and terms + +Use these words and terms in the scenarios described in the following table: + +| Word | Usage notes | +| ------- | ------------ | +| **add** | Use for establishing a new relationship. Often used in create-then-add scenarios. Create a dashboard, then add a visualization. In button labels, always follow _add_ by an object. Remove is the correct opposite. | +| **cancel** | Use to stop an action without saving pending changes. | +| **can't** | Use to indicate you don't have the ability to do something. Often confused with _unable_. | +| **create** | Use for creating an object from scratch. In button labels, always followed by an object. Not _create new_. Delete is the correct opposite. | +| **delete** | Use when deleting data that users can no longer retrieve. Create is the correct opposite. | +| **edit** | Don't use _change_ or _modify_. Edit is the better choice for localization. | +| **enter** | Use for the user entering text. Don't use _type_. | +| **later** | Use when referring to versions of the product. For Example, Elastic Stack 8.13 and later. +| **open** | Use to mean opening an app or program. Don't use _launch_. | +| **press** | Use _press_ for keyboard keys. Don't use _hit_. +| **remove** | Use when removing a relationship, but not permanently deleting the data. For example, you remove a visualization from a dashboard. Add is the correct opposite. | +| **select** | _Select_ is preferred over _choose_. | +| **use**| Use instead of _utilize_ and _make use of_. | +| **view** | Use instead of _see_ because _view_ is more inclusive. | + +## Avoid these words and terms + +This section includes terms that you should avoid in most instances. These terms might be offensive, non-inclusive, unclear, or unnecessary. +Use the alternate suggestions in the following tables or a more specific term. + +### Latin abbreviations + +Latin abbreviations can be unclear. +Use the following suggestions instead: + +| Word | Usage notes | +| ------- | ------------ | +| **e.g.** | Use _for example_ or _such as_ instead. | +| **i.e.** | Use _that is_ instead.| +| **via** | Use _with_, _by using_, or _through_ instead. | + +### Directional language + +Directional language does not meet accessibility requirements and you should avoid it, especially as the only way to find an element in the UI. +Use the following suggestions instead: + +| Word | Usage notes | +| ------- | ------------ | +| **above** | Use a link, _previous_, or _preceding_ instead. | +| **below** | Use a link or _following_ instead| + +### Nouns created from verbs + +Avoid using nouns created from adjectives or verbs. +These words often make text unnecessarily complex. +For example: + +- Use _choose_ instead of _make a choice_. +- Use _register_ instead of _complete your registration_. +- Use investigate instead of _conduct an investigation_. + +### General words and terms to avoid + +Avoid the following words and terms, and use the suggestions instead: + +| Word | Usage notes | +| ------- | ------------ | +| **abort** | Use _shut down,_ _cancel,_ or _stop_ instead. | +| **as well as** | Use _and_ instead. | +| **blacklist** | Use _blocked list_ instead. | +| **boot** | Use _start_ or _run_ instead. | +| **bottom left, bottom right** | Use _lower left_ or _lower right_ instead. Hyphenate when using as an adjective. For example, lower-left corner. | +| **choose** | Use _select_ instead. See Words for interacting with UI| +| **disable** | Use _turn off_, _block_, or _hide_. | +| **enable** | Use _turn on_ or _allow_. | +| **easy**, **easily** | It can be frustrating for users to think that something is easy, but then struggle to do the task. Typically the same meaning can be conveyed without this word.| +| **execute** | Use _run_ or _start_ instead.| +| **hack** | For a noun, use _tip_ or _work-around_ instead. For a verb, use _configure_ or _modify_. | +| **hit** | For a noun, use _visits_ (as in web visits). For a verb, use _select_ or _press_.| +| **impact** | Don't use impact as a verb. Use _affect_ instead. | +| **in order to** | Use simple verbs like _to_ instead. | +| **invalid** | Use _not valid_ or _incorrect_ instead. | +| **just** | Don't use before a command, like "_just_ click here." +| **launch** | Use _open_ instead. | +| **ok** | In button labels, use words that explain the action instead. | +| **normal**, **normally** | Use _usual_ or _typical_ instead. For _normally_ use _usually_, _typically_, or _generally_. +| **please** | In most cases, _please_ is unnecessary. Only use when the user must wait or do something inconvenient. | +| **simple**, **simply** | Unnecessary because it doesn't add any information or value.| +| **sorry** | Use _sorry_ only in error messages that result in serious problems for the user. | +| **success** | Unnecessary because _success_ is generally implied. | +| **terminate** | Use _stop_ or _exit_ instead.| +| **type** | Use _enter_ because there is typically more than one way to enter text. | +| **top left, top right**| Use _upper left_ or _upper right_ instead. Hyphenate when using as an adjective. For example, upper-left corner. | +| **utilize** | Don't use _utilize_ when you mean _use_. | +| **whitelist** | Use _allow list_ instead. | + +## Use caution with these words and terms + +These words and terms might be appropriate in some situations and inappropriate in others. +Only use them when appropriate. + +| Word | Usage notes | +| ------- | ------------ | +| **app**, **application**| Use only when needed for clarity. Otherwise, a Kibana app name can standalone. App is a well-known abbreviation for application and is preferred. | +| **begin** | Use context to decide between _begin_ and _start_. _Begin a procedure_, _begin an analysis_, or _begin an installation_ are common phrases. Similarly, _start a program_, _start an engine_, or _start a timer_ are frequently used. _Start_ is considered less formal than _begin_. _End_ is the correct opposite of _begin_.| +| **can** | Use for capability. Rewrite as an action if possible. For example, instead of _You can add..._ use _Add..._. | +| **click** | OK when describing mouse actions. Otherwise, use verbs that work with multiple devices, such as _select_. | +| **clone** | Use when creating a copy that is linked to the original. Often confused with _copy_ and _duplicate_. | +| **copy** | Use when creating an exact copy in the same location as the original. Often confused with _clone_ and _duplicate_. | +| **disable** | Don't use to describe something that is broken. Use _inactive_, _unavailable_, _deactivate_, _turn off_, or _deselect_, depending on the context.| +| **duplicate** | Use when creating a copy of an object in the same location as the original. Often confused with _copy_ and _clone_. | +| **kill** | Use _cancel_ or _stop_ unless the actual command is `kill`. | +| **may** | Use _may_ for permissibility. Use _can_ for capability. Use _might_ for possibility. | +| **start** | Use context to decide between _start_ and _begin_. _Start a program_, _start an engine_, or _start a timer_ are common phrases. Similarly, _begin a procedure_, _begin an analysis_, or _begin an installation_ are frequently used. _Start_ is considered less formal than _begin_.| +| **unable** | Unable means not being able to perform an action. Often confused with _cannot_. | \ No newline at end of file diff --git a/packages/website/docusaurus.config.ts b/packages/website/docusaurus.config.ts index 4ff84b8eb62..3dfca844af6 100644 --- a/packages/website/docusaurus.config.ts +++ b/packages/website/docusaurus.config.ts @@ -83,6 +83,12 @@ const config: Config = { position: 'left', label: 'Patterns', }, + { + type: 'docSidebar', + sidebarId: 'contentSidebar', + position: 'left', + label: 'Content', + }, { href: 'https://github.com/elastic/eui', label: 'GitHub', diff --git a/packages/website/sidebars.ts b/packages/website/sidebars.ts index 32ad60b3da3..b2a516769a1 100644 --- a/packages/website/sidebars.ts +++ b/packages/website/sidebars.ts @@ -21,6 +21,7 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs'; const sidebars: SidebarsConfig = { rootSidebar: [{type: 'autogenerated', dirName: '.'}], patternsSidebar: [{ type: 'autogenerated', dirName: 'patterns' }], + contentSidebar: [{ type: 'autogenerated', dirName: 'content' }], }; export default sidebars;