Splunk® Style Guide

Splunk Style Guide

Acrobat logo Download manual as PDF


Acrobat logo Download topic as PDF

Write unbiased documentation

Splunk documentation serves a global audience, so it's essential that the documentation reflects the full scope of the Splunk community. Know that words have meanings beyond their dictionary definitions, and strive to write unbiased documentation that considers the experiences of everyone.

Keep the following points in mind when writing about Splunk products to make sure the docs are inclusive:

  • Write in plain language. Metaphors and idioms aren't always understood internationally and can be offensive to some cultures. Read more in Use plain language.
  • Use gender-fair wording and neutral pronouns in your writing. Read more in Gender-neutral pronouns.
  • Choose diverse names and genders when you create use cases and examples. Read more in Names.
  • Make sure your writing meets accessibility standards and requirements. Learn more in the chapter on Accessibility.
  • Avoid biased words, terminology, and language in your writing. Review the following sections on this page.

Determining whether a term shows bias

When writing Splunk docs, be aware of your own biases in your writing. Just because a term isn't offensive to you doesn't mean that it isn't problematic for someone else. To determine whether a term shows unconscious bias or harms a marginalized or underrepresented group, consider the following points:

  • Don't use words that diminish the historical or current situations of others. For example, use "peer" instead of "slave".
  • Don't use words that place a positive or negative connotation on color, race, or people. For example, write "deny list" instead of "blacklist".
  • Don't use words that imply otherness or that exclude a group. For example, use "built-in" instead of "native".
  • Don't use words that harm, degrade, or insult anyone or any group, whether it be mental, physical, sexual, functional, or criminal. For example, use "placeholder data" instead of "dummy data".
  • Don't use words that imply elitism or a position of power. For example, say "primary" instead of "master".

There's a lot of nuance and complexity in the evolving English language, so if a word doesn't fit one of these examples and it makes you uncomfortable, don't use it. If someone tells you that a word makes them uncomfortable, take their opinion as an opportunity to learn. Research the term and discuss its usage with an editor. Everyone deserves documentation that speaks to them rather than against them.

Alternatives to biased language

The following table provides examples of biased language, along with suggested alternatives. The examples in the table aren't exhaustive, but are a starting point to help you consider how to use inclusive language in your writing.

Teams at Splunk are working to remove biased terminology in the products and codebase. You can find official biased terminology replacements in the Usage dictionary.

Biased word or phrase Use this language instead Type of bias
Abnormal Atypical, not typical Ableist, disparaging
Blacklist Deny, deny list, reject, exclude Color bias, racist
Dummy data Placeholder data Disparaging
Flesh-colored, skin-toned Dark brown, cream, beige Color bias
First-class entity Top-level entity Divisive
Grandfathered Exempt Gendered language, racist
Hangs Stops responding, freezes Insensitive, violent
He, him, his, she, her, hers You, your, they, their, them, a user, the users Gendered language, sexist
Hit Click, enter, tap Violent
Illegal characters Special characters Disparaging
Mankind All, everyone, humanity, humankind Gendered language, sexist
Master Manager, primary Divisive, racist
Master branch Main branch Divisive, racist
Native Built-in, fluent Divisive, disparaging
Sanity check Review Disparaging
Slave Peer, replica Divisive, racist
Suicide mode Time until restart Insensitive
Whitelist Allow list, allow, accept, include Color bias, racist

Documenting biased language in the product

Teams at Splunk are working to remove biased language embedded in the products. As a writer, you might see biased terms in the code that you can't change or ignore. In these cases, use unbiased language wherever you can to minimize the instances of a biased term.

Splunk documentation matches the product. If you're referring to a field, a setting in a .conf file, a UI element, or any other part of the product that contains a biased term, you must use the exact name from the product for clarity. In all other cases, such as when describing a functionality rather than a specific part of the product, use unbiased language instead.

Last modified on 22 February, 2021
PREVIOUS
Include alt text in images
  NEXT
Capitalization

This documentation applies to the following versions of Splunk® Style Guide: current


Was this documentation topic helpful?

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters