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 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 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