search

Aiven-Open / klaw-docs

Documentation site for Klaw, our Open Source Apache Kafka® governance toolkit.
https://www.klaw-project.io
Apache License 2.0
5 stars 8 forks source link

Replace / remove use of potential condescending terms #110

Open programmiri opened 1 year ago

programmiri commented 1 year ago

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

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.

AnushkaPhogat16 commented 1 year ago

Hey! I'd like to work on this issue

programmiri commented 1 year ago

Hi @AnushkaPhogat16 thanks for that, we appreciate it 🙏 I'll assign you. Feel free to reach out if you have any questions!

programmiri commented 1 year ago

Hi @AnushkaPhogat16 are you still planning to work on this? Please let me know if not, otherwise I would open the issue up again for other potential contributors :)

I'll check again beginning of next week and if I didn't hear from you, open it again.