Aiven-Open / Aiven-Open/klaw-docs

Replace / remove use of potential condescending terms

Open
#110 3 comments 0 reactions 0 assignees View on GitHub
good first issue help wanted
Dominant language
JavaScript
Stars
4
Forks
10
PR merge metrics
No merged PRs in 30d

Description

# Description

Here's a great explanation what condescending language is and why we should remove it from our documentation: [How to remove condescending language from documentation # Why](https://dev.to/meeshkan/how-to-remove-condescending-language-from-documentation-4a5p#why)

In short, using phrasing like for example: "It is easy to understand this concept." can make people feel inadequate if they don't immediately understand. We humans :D can tend to use that kind of wording from a good place - because we want to assure others that they can do it / don't have to feel intimidated. But we may do the opposite with it.

In order to make our documentation more welcoming, we would like to remove certain words from it, that may invoke that kind of condescending tone. We've added a tool that enables to automatically flag words that are often an indicator for this language. Since the tool can not identify the context, there's a human eye needed to check and formulate the text in a better way.

## Todo

We're using Vale as a tool to check language, and have a style rule that flags certain words. There are two ways this can help you:

1. You can run `npm run spell:warn`.
This will log all errors (should be zero 😅 ) and warnings. I you search this logs for `Klaw.language-condescending`, you will find the places where Vale found potential issues. There will be more warnings from other rules.

2. Temporary change level for the rule
Search for the file `language-condescending.yml` and change the level from warning to error: `level: error`
Run `npm run spell:error`. This will show you only errors, so it's a less messy log. Please remember to set the level to "warning" again before you commit, as we do not want to enforce this style rule.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.