search

get-alex / alex

Catch insensitive, inconsiderate writing
https://alexjs.com
MIT License
4.81k stars 208 forks source link

Add `Further reading` section #286

Open wooorm opened 4 years ago

wooorm commented 4 years ago

Problem

  1. This project assumes that people know why it is important to use more considerate language.
  2. And as this project turns being considerate into a checklist, it may lead folks to think that when alex is used on docs, those docs will be perfect.

Expected behaviour

The readme, and the website, should answer this information, perhaps in the form as a list of prereqs, that answer 1, and some form of further exercises, that answer 2.

w-t-effi commented 4 years ago

Would it maybe make sense to include this in the tool itself, and propose a specific resource for each issue in the text? I feel like just adding a section to the readme and the website will not be as helpful because people might only use the tool itself without wanting to reading about it first. Also, I think a further reading section would either be too broad ( e.g. slave/master and white-listing are both examples of racist language but require different explanations as to why not to use them) or too specific (too many links/resources might deter readers). I would love to hear your opinion on this.

I realise of course this would require a lot more work, so I'd still like to help with assembling a list of resources.

wooorm commented 4 years ago

Hi Effi!

We have some of that in the tool indeed: some urls and short descriptions with reasoning and a bit more explanation. We could use more of that though. And as they’re about specific words: also useful, but very specific.

The issue I want to solve here, is more of a broader explainer to educate folks in general about why language matters. Not lists of words to (not) use!

alex is currently explained as something that solves your language, whereas I hope to shift that more to: humans solve language, here’s a list of resources to learn more about why that’s important, and: use alex to help catch some stuff!

jenweber commented 4 years ago

I can write a short blurb for the alex homepage, to get this started. I am planning to spend some time on open source/Hacktoberfest this upcoming Thursday. If anyone else wants to help out, let me know and we can collaborate!

wooorm commented 4 years ago

That’s awesome! Thanks Jen! And indeed: looking for more folks who have suggestions or want to help!

jenweber commented 4 years ago

@w-t-effi if you have time, it would be awesome if you could have a look at the PR, https://github.com/get-alex/alex/pull/306 and see if there's anything you would add or change. Thank you!

w-t-effi commented 4 years ago

@jenweber yes, absolutely! I should find the time sometime next week.