diversity and inclusion in developing graspologic

[jovo]

what are the practices that we can & should adopt to ensure that we create a developer community that is diverse and inclusive? i imagine there are certain things we can write in the contribution guidelines, but also other things we may want to do with respect to community building. if there are good examples of FOSS that exhibit the characteristics that we are striving for, if would be good to list them here.

[bdpedigo]

https://twitter.com/kne42/status/1307513850133053443

[bdpedigo]

at some point i did see a thread on twitter in response to the numpy stuff that had a lot of ideas but i can't find it now

[bdpedigo]

https://numpy.org/diversity_sep2020/

[bdpedigo]

mozilla checklist https://github.com/mozilla/inclusion/blob/master/evaluation_tools/governance-basic.md
(from https://twitter.com/kne42/status/1316212780387590146)

[bdpedigo]

other recommendations from the above:

• Rails Girls Summer of Code (call for projecs in 2020 was 06 Jan - 10 Feb 2020)
• GSoC (google summer of code)

[bdpedigo]

this whole repo seems super useful https://github.com/mozilla/inclusion

[bdpedigo]

also another great compilation of resources it looks like https://opensourcediversity.org/

[bdpedigo]

Possible action items (based on the above) (to be broken out into issues later)

• Explicitly add a code of conduct
  • I think we technically have this via Microsoft but should make it more explicit/apparent
  • Mozilla recommends having in root of the repository or main project page.
  • Clearly states how to report behaviors that violate COC, who they go to, clear expectations of what to expect after a report. Perhaps already in the MSFT one?
• Clarify leadership/"roles of influence"
  • "It's easy to understand who the project leaders are (maintainers, committers, community team)."
  • "The roles of leadership in a project are publically documented."
• Channel for communication (no)
  • Mozilla thing recommends some kind of public chat like slack, forums, etc.
  • Personally, I prefer keeping almost everything on GitHub via PRs and issues. Though I could see how this is perhaps less approachable to a new user? Thoughts?
• Accessibility testing
  • Guide to testing for accessibility
• Reserve issues for new people only
  • The case for doing this
  • We do use the "good first issue" label currently. Maybe we can curate it better somehow?
  • Could add ourselves to something like upforgrabs or firstcontributions
  • "Non-technical tasks helpful for first-time contributors to learn about, and participate in a project are available."
• Employement/internship
  • RailsGirls Summer of Code
  • Outreachy
  • GirlScript
  • There are a ton more on this not sure how to evaluate which would be best for us. maybe any?
  • Funding for underrepresented groups in grants?

[bdpedigo]

Jovo: good for people to know who they can ask questions to (re: leadership clarification)

[bdpedigo]

maybe we clarify that "issues" can be random questions (could be part of the issue template)

[bdpedigo]

Action items (as I see it, feel free to add opinons)

Items in bold I think can be coordinated for any neurodata repo

1. Explicitly add a code of conduct (repo-specific)
2. Clarify leadership/"roles of influence" (repo-specific)
3. Clarify that issues can be random questions
   • someone could write an issue template and use for all repos
4. Accessibility testing
   • someone could spearhead/guinea pig how to do this first
   • then will be repo-specific
5. Issues for new people only
   • reserving issues will be repo specific
   • figuring out what sites to add ourselves to could be cross-repo
6. Employement/internship (@tathey1)
   • researching the different programs could be cross-repo

[tathey1]

Might match agreements best if I am the last bullet.

I would also be interested in discussing how the first bullet may vary across repos.

[carolyncb]

Here's the example Mozilla uses of an inclusive leadership page: https://github.com/firefox-devtools/debugger/blob/aa827095d86475f816017ff35d6f9c2e83cf7b9b/docs/community-team.md. It strikes me as very welcoming and lets new people know exactly who to reach out to for a number of questions.

[bdpedigo]

@carolyncb that is a great example, thank you!!

[bdpedigo]

Might match agreements best if I am the last bullet.

I would also be interested in discussing how the first bullet may vary across repos.

Sounds good, i'll tag you for that one @tathey1

[bdpedigo]

@sampan501 would you have any interest in looking into sites for "good first issue" like the ones I linked above and seeing how we can add ourselves?

@rflperry would you have any interest in looking into the accessibility testing stuff?

I can make a template for "Random question issue" and draft a "roles of influence" template based on what @carolyncb linked.

Happy to hear it if anyone has other stuff they'd rather work on or doesn't want to commit to these. Or if anyone else wants to pitch in somehow, lmk

[rflperry]

@bdpedigo Yeah can totally look into that! Thanks for delegating

[sampan501]

Sounds great, I'll look into that

[carolyncb]

@rflperry Microsoft has an internal accessibility checklist that I'm not sure I can share, but I found this list that looks very similar: https://www.hhs.gov/sites/default/files/hhs-508-webapps-checklist.xlsx (from https://www.hhs.gov/web/section-508/accessibility-checklists/index.html). It's pretty exhaustive, and not all the points will apply, but it helps to give an understanding of areas of focus.

[sampan501]

@bdpedigo This link you gave gives really good links to websites that conglomerate issues with the good-first-issue label: https://www.firsttimersonly.com/. Another good app is this, which tweets out anytime you use the good-first-issue label: https://github.com/apps/goodfirstissue. I think the minimum we have to do is to update our contribution guides with what the label means and how much work is involved.

[rflperry]

Accessibility

As far as I know, all of our webdocs are rendered using sphinx which makes some things difficult but also makes things easier. An important part of accessibility is that the webpage is appropriately structured, in a hierarchical manner with correct headers etc. Sphinx makes sure this is the case.

Raw html code can be entered into this html code sniffer website which will let you know of any issues, although some issues it's given me in my own testing don't make sense and I think are just an artifact of the sphinx style.

A good concise list of things to keep in mind, some parts of which I highlight below.

Colors

One of the more common accessibility issues.

1. For figures (i.e. in notebooks which will be rendered), use palettes from color brewer palette generator and make sure to select the colorblind safe option

2. Non-text content should use patterns in addition to color to distinguish (i.e. varying shape and color on a plot)

3. Links should be underlined, have a greater than 3:1 contrast with the body text, and there should be a visual indication when your cursor hovers over them. This online link contrast checker can help. At least in mvlearn documentation, our sphinx links are not underlined and are (barely) not contrasted enough. Not sure if this is currently fixable (see open sphinx issue and haven't been able to find a way to underline all links.

Links

Besides link color contrasts, links should be descriptive and no "click here" sort of things. The purpose of a link should be able to be determined from the link text alone or from its surrounding context.

Alternative text

Images and other multimedia should have descriptive text so that a screen reader can describe what an image is showing. This can be done in sphinx with with the ":alt: alternative text here" descriptor under an image as described in their documentation.

Keyboard

Sphinx builds the webdocs in a very structured manner and so the docs are easily navigated using a keyboard (tab/shift+tab and enter) by default. Sphinx is also free of widgets and fancy things that would potentially get in the way. Details for reference.

Other

A detailed checklist, as mentioned above, can be seen on this downloadable sheet. A lot isn't relevant since we don't directly touch html/css files or have interactive items but I've laid out things I think are relevant to keep in mind.

• Linked/downloadable pages and files should also be accessible. So avoid unnecessary ones.
• Items on the webpage should not be references by sensory characteristics including shape, size, or visual location (i.e. "instructions are in the right-hand column")

[jovo]

what is the status of this? can we complete everything and close this issue this week?
@bdpedigo @rflperry @tathey1 @sampan501

[tathey1]

In brainlit we addressed several items here. We still need to do accessibility testing, and there could be better "good first issues" added.

However we are thinking we might want a lab code of conduct that we can all refer to - see this PR.

[bdpedigo]

specifically for closing this issue with regard to graspologic, by mid-next week (12/23) I will:

• make the dedicated roles/responsibilities page more visible, either in wiki or preferably on the docs or higher up in github
• make sure we have a healthy dose of good first issues and add us to at least one of those references Sambit linked
• at least make a specific issue for graspologic for the accessibility stuff. from Ronan's summary I suspect that:
  • we may have issues with colors and lack of color + non-color signaling in many figures in the docs
  • the issue with contrast in sphinx, im guessing there is a simple css setting somewhere that controls it but would take me a while to find
  • links may not conform to the specified "descriptiveness"
  • not sure how alt text works for figures in a jupyter notebook

[bdpedigo]

made a PR for graspologic to be added to up-for-grabs up-for-grabs/up-for-grabs.net#2524

[bdpedigo]

also made a PR to DeepSourceCorp/good-first-issue#188

[bdpedigo]

Closing for now but happy to revisit as we get feedback or if anyone has concerns.

For now, to document all the concrete steps that we took:

• Add "Roles" to top of repo #616 simple PR is opened for adding an explicit "Roles" page, which will be more visible than having it in the wiki
• Added graspologic to open source "good first issue" lists
  • adding graspologic up-for-grabs/up-for-grabs.net#2524 merged
  - https://github.com/add microsoft/graspologic DeepSourceCorp/good-first-issue#188 merged
• Remaining concerns on doc accessibility split into Audit docs for accessibility #617
• merged code of conduct page neurodata/neurodata.io#418 for code of conduct for other neurodata repos that are not this one to use
• A while ago we added this issue template for random questions as a way of trying to make it less intimidating to ask. I suspect this may evolve with the addition of GitHub Discussions (currently a beta, I believe) which sort of fills the gap that we discussed for letting anyone ask questions in a low stakes way.