Menu
Open source

Inclusive writing

When writing for Grafana Labs, always use inclusive terminology and phrasing. Avoid all statements that perpetuate gender, racial, or cultural stereotypes. Don’t use gendered words or demographically oriented terms that are irrelevant to the content.

Write about people

When writing about people, be compassionate, inclusive, and respectful.

No matter the context, we always make sure to view people as people. With that in mind, there are important distinctions between the ways that different people interact with our product and, thus, how we refer to those people.

  • Users are every person who uses our products, whether or not they use a commercial version of one of our products. Customers are people and companies who pay to use our products.
  • Visitors are people who visit our website for any reason, whether it’s as a potential user, customer, or employee. We appreciate all interest in our hard work.
  • Our customers (and users) often have their own customers (and users). Generally speaking, we refer to these customers of our customers as users.
  • Employees are people who work at Grafana Labs.

Best practices

Consider the following best practices to ensure inclusivity in your writing.

  • Group or audience: Don’t refer to a group or audience as it. Instead, use they.
  • Age: Don’t refer to someone’s age unless it’s relevant. Don’t use age-related words to describe people. Avoid: young, old, or elderly.
  • Hearing: Do use the adjectives deaf, partially deaf, or hard of hearing when describing a person with hearing loss.
  • Vision: Do use the adjective blind or low vision when describing a person with limited vision.

Write for an international audience

Grafana Labs uses US English as our standard for spelling, grammar, punctuation, and more. We write for an international audience with the following guidelines in mind:

Avoid acronyms

If you use an acronym, first write out each word in the acronym on first use, and then continue using just the acronym.

  • Example: Grafana Cloud is software as a service (SaaS). Using SaaS typically requires setting up an account.

Avoid idioms

Understanding idioms typically requires cultural context. Users of Grafana Labs products and projects are all around the world, and many are non-native English speakers. Therefore, avoid idioms and idiomatic puns.

For example, some common American English idioms:

  • Costs an arm and a leg
  • Hit the nail on the head
  • Bite off more than you can chew

Here are some more obscure British idioms:

  • A few sandwiches short of a picnic
  • Chuffed to bits
  • Over-egg the pudding

Avoid cultural references

Cultural references are references that relate to the culture of a community, country, continent, and so on.

Examples:

  • Her ambition is a clear reflection of the American dream.
  • You came to help like a good Samaritan.
  • They grew up in a typical nuclear family.

Avoid charged language

Avoid using charged language such as blacklist, master, and slave.

Allow, block

Avoid whitelist or blacklist.

When referring to allowing or blocking content or traffic, use a form of allow or block:

  • For the noun form, use allowlist or blocklist
  • For the verb form, use allow or block

Example: To allow outgoing traffic, add the IP to the allowlist.

Primary and secondary

Avoid master or slave.

Use the following approach to describe relationships between nodes or processes:

  • Use primary, main, or parent, instead of master.
  • Use secondary, replica, or child, instead of slave.

Right and left

Use the terms right and left with a qualifier like top or lower to help individuals with cognitive disabilities or those using screen-reading software.

Hyphenate when you’re modifying a noun. For example:

  • in the top-right corner
  • at the bottom left of the dialog box
  • the upper-left section
  • scroll toward the lower right

Don’t use the word hand as a qualifier like in right-hand corner.