Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Further reading section #286

Open
wooorm opened this issue Jun 24, 2020 · 6 comments
Open

Add Further reading section #286

wooorm opened this issue Jun 24, 2020 · 6 comments
Labels
📚 area/docs This affects documentation help wanted 🙏 This could use your insight or help 🙆 status/confirmed This is open and confirmed: ready to be worked on 🦋 type/enhancement This is great to have

Comments

@wooorm
Copy link
Member

wooorm commented Jun 24, 2020

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.

@wooorm wooorm added help wanted 🙏 This could use your insight or help 📚 area/docs This affects documentation 🙆 status/confirmed This is open and confirmed: ready to be worked on 🦋 type/enhancement This is great to have labels Jun 24, 2020
@w-t-effi
Copy link

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
Copy link
Member Author

wooorm commented Aug 21, 2020

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
Copy link
Contributor

jenweber commented Oct 3, 2020

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
Copy link
Member Author

wooorm commented Oct 3, 2020

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

@jenweber
Copy link
Contributor

jenweber commented Oct 9, 2020

@w-t-effi if you have time, it would be awesome if you could have a look at the PR, #306 and see if there's anything you would add or change. Thank you!

@w-t-effi
Copy link

w-t-effi commented Oct 9, 2020

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

jenweber added a commit to jenweber/alex that referenced this issue Oct 15, 2020
Partially addresses get-alex#286

Capitalization
wooorm pushed a commit that referenced this issue Nov 3, 2020
Related to: GH-286

Closes GH-306.

Reviewed-by: Titus Wormer <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
📚 area/docs This affects documentation help wanted 🙏 This could use your insight or help 🙆 status/confirmed This is open and confirmed: ready to be worked on 🦋 type/enhancement This is great to have
Development

No branches or pull requests

3 participants