Splunk® Style Guide

Splunk Style Guide

The guidelines in the Splunk Style Guide establish best practices for writing technical documentation. Search docs.splunk.com to find documentation related to Splunk products.

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.

When writing about Splunk products, keep inclusivity in mind and follow these guidelines:

Guideline Additional information
Write in plain language. Metaphors and idioms aren't always understood internationally and can be offensive to some cultures. Use plain language
Use gender-fair wording and neutral pronouns in your writing. Gender-neutral pronouns
Choose diverse names and genders when you create scenarios and examples. Names
Make sure your writing meets accessibility standards and requirements. Write accessible documentation
Avoid biased words, terminology, and language in your writing. Alternatives to biased language

Determining whether a term shows bias

When writing Splunk docs, be aware of your own biases in your writing. A term that isn't offensive to you might be 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 "everyone" instead of "mankind".
  • 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 euphemisms to describe disabilities. For example, use "person with a disability" over "a differently abled person".
  • Don't use words that imply elitism or a position of power. For example, write "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 instead are meant to act as a starting point to help you consider how to use inclusive language in your writing. You can also look for other 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
Disable, disabled, disables Deactivate, deactivated, deactivates, deselect, deselected, deselects, hide, hidden, hides, inactive, turn off, turned off, turns off, unavailable, makes unavailable Divisive, disparaging
First-class entity Top-level entity Divisive
Flesh-colored, skin-toned Dark brown, cream, beige Color bias
Grandfathered Exempt Gendered language, racist
He, him, his, she, her, hers You, your, they, their, them, a user, the users Gendered language, sexist
Illegal characters Invalid characters Disparaging
Mankind All, everyone, humanity, humankind Gendered language, sexist
Master Manager, primary Divisive, racist
Master branch Main branch Divisive, racist
Sanity check Review, verification Disparaging
Slave Peer, replica Divisive, racist
Whitelist Allow list, allow, accept, include Color bias, racist

Writing about disability communities

If you need to write about a member of the disability community, use the language preferred by the individual or the specific audience you're describing. Some communities, such as the autism community and the Deaf community, prefer to use identity-first language. If you're writing about disability communities in general, use person-first language. Both languages are acceptable depending on the audience you're writing for. Review the following table for examples:

Do this Don't do this
An autistic person A person with autism
A person with disabilities A disabled person

For more guidance on disability language, see the National Center on Disability and Journalism's Disability Language Style Guide at https://ncdj.org/style-guide/.

What about other words?

You might have questions about other types of words, such as violent language, potentially distressing terminology, or phrases that mention a color. Terms that are not inherently biased aren't listed in the Alternatives to biased language section, but you are always welcome to write with more thoughtful language.

Documenting biased language in the product

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

Splunk documentation matches the product. If your situation aligns with any of the following examples, match the exact name from the product for clarity:

  • A field in Splunk software
  • A setting in a .conf file
  • A UI element
  • Any other part of a Splunk product
  • An outside source or system

In all other cases, such as when describing a functionality or a general concept rather than a specific part of the product, use unbiased language instead. See Alternatives to biased language for examples.

Last modified on 12 February, 2024
Include alt text in images   Use device-agnostic language

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

Was this topic useful?

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