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.
