Skip to content

Commit 06415e3

Browse files
florent-leborgneflorent-leborgne
committed
Content section
1 parent 8e9df72 commit 06415e3

File tree

9 files changed

+673
-0
lines changed

9 files changed

+673
-0
lines changed

‎packages/website/docs/content/accessibility.mdx

+84
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
id: content_accessibility
3+
slug: content-accessibility
4+
---
5+
6+
# Accessibility
7+
8+
This page shares common tips and tricks for writing accessible UI copy. It is not exhaustive and does not replace the official
9+
[WCAG 2.0 guidelines](https://www.w3.org/TR/2008/REC-WCAG20-20081211/#guidelines).
10+
11+
12+
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.
13+
14+
15+
## What is accessible content and why does it matter
16+
17+
**Accessibility** for content means making sure that the content can be consumed properly, independently of how users choose or have to interact with it.
18+
19+
Our users and readers are diverse, with different abilities, and disabilities.
20+
They also interact with our content in different ways: screen readers, mobile devices, Braille, and so on. The list is long, and always evolving.
21+
22+
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).
23+
24+
## Guidelines
25+
26+
✔️ **Make your content scannable.** A clear structure and meaningful words tell users if the feature or flow is relevant to them within seconds.
27+
28+
✔️ **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.
29+
30+
31+
| Inaccessible | | Accessible |
32+
| --------------------- | --- | ------------------------- |
33+
| Image of in progress rule creation form. | → | User is setting up a new threshold rule. |
34+
| Logs integrations | → | Integrations that let you to ingest logs. |
35+
36+
37+
✔️ **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.
38+
39+
40+
| Inaccessible | | Accessible |
41+
| --------------------- | --- | ------------------------- |
42+
| Update the sourcerer selection to be the default detections data view. | → | Choose the default Security data view. |
43+
| **Cancel update rule?** You will lose changes to the rule. | → | **Discard rule changes?** Select **Discard** to reject these changes. |
44+
45+
46+
✔️ **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.
47+
48+
49+
| Inaccessible | | Accessible |
50+
| --------------------- | --- | ------------------------- |
51+
| Click here for more information. | → | Learn more about indices. |
52+
| Create a query. Learn more. | → | Learn how to create an ES\|QL query. |
53+
54+
55+
✔️ **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.
56+
57+
58+
| Inaccessible | | Accessible |
59+
| --------------------- | --- | ------------------------- |
60+
| Type in your username and password. | → | Enter your username and password. |
61+
| Select a time range for the Alerts table. | → | Choose a time range for the Alerts table. |
62+
63+
64+
✔️ **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.
65+
66+
67+
| Inaccessible | | Accessible |
68+
| --------------------- | --- | ------------------------- |
69+
| Complete the form below. | → | Complete the following form. |
70+
| Import values from a file by clicking the **Import values** button under the table. | → | Select **Import file** to import values from supported file types. |
71+
72+
73+
## Words to avoid
74+
75+
Avoid the following words. Use the suggestions instead.
76+
77+
| Avoid | | Use instead |
78+
| --------------------- | --- | ------------------------- |
79+
| Click, tap | → | Select, choose |
80+
| Above, over | → | Preceding, previous |
81+
| Below, under | → | Following, further, later |
82+
| See | → | Check, refer to |
83+
| Hear (hear about...) | → | Learn |
84+
| Type | → | Enter |

‎packages/website/docs/content/adapt-tone.mdx

+183
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
---
2+
id: content_tone
3+
slug: content-tone
4+
sidebar_position: 20
5+
---
6+
7+
# Tones
8+
9+
Adapt the way you write to each situation users can face.
10+
11+
Our products and solutions are very technical, data-oriented, and they're used globally by people from different cultures, abilities, and personalities.
12+
These considerations, amongst others, limit the spectrum of tones we use to some extent, but not entirely.
13+
14+
During the users' journey with Elastic, there are times for excitement and discovery, but also times for help, support, and empathy.
15+
16+
17+
## Stimulating
18+
19+
**Attributes**
20+
21+
We're proud to show new and cool stuff. Be:
22+
23+
- Motivational
24+
- Excited
25+
- Enthusiastic
26+
27+
When using this tone, you may:
28+
- Use exclamation marks, but sparingly.
29+
- Take time to help the user understand how this feature benefits them.
30+
- Use visuals to support your text.
31+
32+
**Cases**
33+
34+
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.
35+
36+
We use it when we want to show new things to users, especially in:
37+
38+
- Product tours
39+
- New feature announcements
40+
41+
## Friendly
42+
43+
**Attributes**
44+
45+
All's fine, we'll help you find your way. Be:
46+
47+
- Calm
48+
- Positive
49+
- Confident
50+
51+
When using this tone, you may:
52+
- Use more casual terminology.
53+
- Explain what's missing or what's happening.
54+
- Provide actions or clearly state when there's no action needed.
55+
56+
57+
**Cases**
58+
59+
The **friendly** tone is used **sparingly** overall and usually blends in the UI at different moments of the users' journey.
60+
61+
We use it when orienting users in doing their next action or learning different things they could do, especially in:
62+
63+
**UI**
64+
- Empty states (no item created or no matching results)
65+
- Loading and waiting states
66+
- Tips
67+
- Success messages
68+
- Welcome emails (signup & trial)
69+
70+
**Documentation**
71+
- Quick starts
72+
- Tutorials
73+
74+
## Informational
75+
76+
**Attributes**
77+
78+
E=MC². Be:
79+
80+
- Direct
81+
- Straight to the point
82+
- Neutral
83+
84+
When using this tone:
85+
- Use a minimum of words.
86+
- Write for scanning and help users quickly locate what matters to them.
87+
- Use action verbs to:
88+
- Label selection controls.
89+
- Describe what settings do or what to do with a setting.
90+
- Use clear nouns for
91+
- menus, form field names
92+
93+
94+
**Cases**
95+
96+
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!
97+
98+
We use it for naming and describing things:
99+
100+
- Menus, titles, setting names, hint text, placeholders, introductions, and descriptions
101+
- In-product assistance (tooltips, help popovers, guided setups)
102+
- Information callouts
103+
- Confirmation modals
104+
- Calls to action (buttons and links)
105+
- Event logs
106+
107+
**Documentation**
108+
- Reference content
109+
- Concepts
110+
- How-tos
111+
- Troubleshooting
112+
113+
## Empathetic
114+
115+
**Attributes**
116+
117+
Something might be wrong and requires attention. Let us help you. Be:
118+
119+
- Reassuring
120+
- Professional
121+
- Precise
122+
123+
When using this tone, you may:
124+
- Be more action-oriented than usual to offer direct paths to users.
125+
126+
127+
**Cases**
128+
129+
The **empathetic** tone is used **sparingly** overall and is usually shown in places that draw the user's attention.
130+
131+
We use it when notifying users of things that are not immediately critical but still require attention, especially in:
132+
133+
- Warnings and cautions
134+
- Upgrade and deprecation notices
135+
136+
## Supportive
137+
138+
**Attributes**
139+
140+
Something is definitely wrong. Here's why, and how to fix it. Be:
141+
142+
- Serious
143+
- Concerned
144+
- Urgent
145+
146+
When using this tone, you may:
147+
- Focus on what went wrong. Don't be apologetic.
148+
- Help users learn how something happened, how to prevent it, how to fix it.
149+
- Provide clear actions, or clearly state it if there's no action needed.
150+
151+
152+
153+
**Cases**
154+
155+
The **supportive** tone is used **sparingly**. It usually becomes visible in forms that draw the user's attention, for example, through callouts or notifications.
156+
157+
We use it when the immediate attention of the user is required, especially in:
158+
159+
- Errors
160+
- Licensing or billing-related content
161+
- Vulnerability and remediation content
162+
163+
## Stern
164+
165+
**Attributes**
166+
167+
We don't advise this action, but you're the master of your destiny. Be:
168+
169+
- Deterring
170+
- Heavy with caution
171+
- Advisory
172+
173+
When using this tone, you may:
174+
- Use stronger words that highlight possible negative effects.
175+
- Format the content in a way that make the risks stand out.
176+
177+
**Cases**
178+
179+
The **stern** tone is **rarely** used. Reserve it for very specific cases, and for advanced or administrative features.
180+
181+
We use it when insisting on the high risks an action could pose, especially in:
182+
183+
- Danger type of warnings

‎packages/website/docs/content/inclusivity.mdx

+106
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
id: content_inclusivity
3+
slug: content-inclusivity
4+
---
5+
6+
# Inclusivity
7+
8+
This page provides guidelines for writing inclusive UI copy for product content but it's not exhaustive.
9+
10+
## What is inclusive content and why does it matter
11+
12+
**Inclusivity** for content means making sure that the content we serve reflects the diversity of our community, respects it, and promotes positive change.
13+
14+
15+
## Guidelines
16+
17+
### Write for an international audience
18+
19+
Our products use American English (en_US) as a standard for written content.
20+
Yet they are used, read by persons all around the globe, for whom English is not always their primary language.
21+
Our content must take that into account.
22+
23+
✔️ **Aim for simplicity.** Indeed, we are a technical company, writing for
24+
technically-savvy users. However, it benefits everyone if we try to keep our writing as simple as possible.
25+
26+
* **Short sentences** - They leave less space for interpretation. They are easier to scan, read, and translate.
27+
28+
* **Plain language** - Use active voice, present tense, using examples, and so on.
29+
Some of these guidelines might already look familiar. Several countries have
30+
[plain language initiatives](https://www.plainlanguage.gov/guidelines/) to
31+
promote clearer communication. Do your
32+
best to embrace these guidelines and focus on the message.
33+
34+
* **Negation** - It is easier to say what something IS
35+
versus what it is NOT. When you add a negative construction, it takes the
36+
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."
37+
38+
* **Words with multiple meanings** -
39+
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.
40+
41+
✔️ **Be aware of differences and diversity in content and examples.**
42+
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.
43+
* 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.
44+
* If there is no obvious example standard (RFC) to follow, try to be diverse to represent our audience.
45+
46+
✔️ **Avoid idioms or expressions that are not commonly known, a.k.a regionalisms.**
47+
48+
In our Elastic documentation we aim for a fun, friendly, and sometimes quirky
49+
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:
50+
51+
* Idioms (for example, _It's a piece of cake_ or _So far so good_)
52+
* Regional expressions (for example, _G'day!_, _Y'all_, or _eh_)
53+
* Sports expressions (for example, _touched base_ or _threw a curve ball_)
54+
* Pop culture references (for example, _Elvis has left the building_ or _Same bat-time, same bat-channel_)
55+
56+
We're all pretty good at avoiding these, but there's one problematic type of
57+
expression that sometimes shows up in UI copy. Latin terms and
58+
abbreviations are a common source of confusion, particularly for people whose
59+
first language does not have Latin roots.
60+
61+
Here are some terms to avoid and suggested alternatives:
62+
63+
| Avoid | | Use instead |
64+
--- | --- | ---
65+
| _e.g._ (exempli gratia) | → | _for example_ |
66+
| _etc._ (et cetera) | → | _and more_ or _and so on_ |
67+
| _i.e._ (id est) | → | _that is_ |
68+
| _via_ | → | _by way of_, _by means of_, or _through_ |
69+
70+
✔️ **Aim for readability.** Tools like the [Hemingway App](https://hemingwayapp.com/) can help you make content simpler. Be conversational, but prioritize clarity.
71+
72+
### Use gender-neutral language
73+
74+
Writing gender-neutral mainly consists in avoiding gender bias and word choices implying that one gender is the norm.
75+
76+
✔️ **Pronouns.** In the UI, this can be avoided by addressing users directly.
77+
When it's not possible, use *they*/*their*, even for singular. There's more than one gender, and it's not binary either.
78+
79+
✔️ **Biased words and expressions.** Guys, mankind, policeman... Words that we're all used to hear and use. But the default is not male.
80+
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...
81+
82+
### Avoid violent, offensive, ableist terminology
83+
84+
Earlier in this page, we discussed avoiding ambiguous terms, especially when a word's intended meaning is
85+
not its primary meaning. Other types of words and phrases best avoided are:
86+
87+
* buzzwords (_incentivize_, _synergies_)
88+
* superhero terms (_rockstar_, _wizard_, _ninja_)
89+
* violent imagery (_crush the competition_)
90+
* non-specific superlatives (_unrivaled_, _unparalleled_, _world class_)
91+
92+
Some words have nuances that fall into the above categories, which may cause
93+
them to be misinterpreted. Here are some alternatives:
94+
95+
| Avoid | | Use instead |
96+
--- | --- | ---
97+
| Abort | → | _stop_, _cancel_, or _end_ |
98+
| Boot | → | _start_ or _run_ |
99+
| Execute | → | _run_ or _complete_ |
100+
| Hack (noun) | → | _tip_ or _workaround_ |
101+
| Hack (verb) | → | _configure_ or _modify_ |
102+
| Hit (verb) | → | _click_ or _press_ |
103+
| Hit (noun) | → | _visits_ (as in _website visits_) |
104+
| Invalid | → | _not valid_ or _incorrect_ |
105+
| Kill | → | _cancel_ or _stop_ |
106+
| Terminate | → | _stop_ or _exit_ |

0 commit comments

Comments
 (0)