[ENH] - Restructure this repo and adopt a compass

[trallard]

This is related to #67 - or rather builds on it.
Right now this repo seems to have become a "one-stop for all things accessibility" which is good because folks come here to ask questions and help with general visibility.

But as folks like myself, @gabalafou, @isabela-pf and @tonyfast are working on coding-related outputs for the CZI grant these ended up landing here.
There is also the open PR to make this into an official subproject (see this PR in the governance repo).

I think it is time to formalize this repo as well as some of our processes:

1. We should adopt a team-compass style repo/documentation (for reference see the JupyterHub team compass) - we will need this eventually within the new governance model
2. All of the content in our current docs/site should live wherever the team compass lives that will keep all the governance, processes, and broader documentation altogether
3. The software and testing outputs should live in another repo, including:
   1. Accessibility tests such as the ones added in Axe Gitpod JupyterLab #83 and Developer tooling for building/testing jupyter artifacts #84
   2. Accessibility related tooling and templates
   3. Actions and artefacts aimed at a11y testing/auditing
      So basically this repo would be something similar to https://github.com/jupyterlab/benchmarks but "Accessibility tools for Jupyter"

I think this would make it easier to manage/maintain as well as provide more clarity on what users and contributors can expect to find in each repo.

Now the options

1. Keep this as the "team compass" and migrate the "tooling" to another repo maybe `jupyter/accessibility-tools"
2. Keep this repo for the "tools" and create a `jupyter/accessibility-team-compass"

Either way, I think this is a necessary move to keep things consistent, easy to maintain and prevent having to have multiple times the structure discussion as this happened also through the review in #83

[trallard]

I forgot to mention - I volunteer myself to do the re-org as needed and update docs/set docs and the such

[gabalafou]

Will it be easy for us to create repos at the Jupyter org level? Such as jupyter/accessibility-testing and jupyter/accessibility-theming etc.?

Or would we need to follow the jupyter-contrib pattern, like so:

github.com/jupyter-accessibility/team-compass
github.com/jupyter-accessibility/testing
github.com/jupyter-accessibility/theming

?

[trallard]

I will defer this to someone with more knowledge like @Carreau @afshin or @jasongrout

[jasongrout]

If we are using only two repos, I'd suggest just creating the one more repo in this org. If there is an immediate need for many more repos, then creating an org is probably worth it.

[trallard]

Should only need the two 🙂

[jasongrout]

Great, I'm happy to create either a -tools repo or a -team-compass repo, whichever everyone decides on.

[isabela-pf]

In terms of next steps, I think the pattern of adding a team-compass repo that points to the existing jupyter/accessibility project is the common pattern and the one that makes the most sense to continue.

Sorry for the delayed reply. I feel like this is a premature break (the repo is still small) that, honestly, is going to

• divide the already tiny community
• require more effort to keep track of where things go
• once again separate perceived software from community and, personally, once again put me in community-only zone.

I also am not sure if this would impact the open jupyter/governance PR that points to this repo, though I imagine we could still make changes there.

Is there a reason this came up now? I'm guessing it's because of the repo clean up and the shift of what's been going in the repo. I also thought this might be a governance requirement, but couldn't find it in the docs.

I won't get in the way of this work and am happy to help if it happens, I just wanted to voice my concerns. I understand why this could be an important long-term choice and I think there is precedent for it.

[afshin]

I think that @trallard's #2 option: having a team repository (jupyter/accessibility-team-compass) for votes, minutes, administrative conversation, events, and denoting who is in the Jupyter Accessibility Council is a good idea. Once the vote for making Jupyter Accessibility an official Jupyter Subproject passes, there will need to be a place where this sort of information is kept up to date. And I agree that the primary repo for software artifacts and other work that doesn't end up in another Subproject's repository does seem like it is best served by residing in this one: jupyter/accessibility.

I'm happy to help in whatever way you folks deem best. Thank you, @jasongrout for offering to make the repository. The cookiecutter template for team-compass repositories is still a work-in-progress. But it might be a good starting place to save some time.

@isabela-pf I hope this doesn't seem like it splits the team. To me, it seems like a question of "how do we organize the issues and artifacts we use for administration and keep them separate from the issues and artifacts that we functionally produce?"

[trallard]

@afshin @jasongrout we will keep this repo as our canonical accessibility repo and in the meantime incubate the tools work into the Quansight-Labs GitHub organisation. WE might need a couple more months to decide the happy path: repos, organisation?

Will definitely be touching base with y'all

[jasongrout]

Thanks for the update, Tania. I'm curious: what is preventing work from the Jupyter Accessibility group being done in a Jupyter repo?

[trallard]

Glad you ask Jason. This is a discussion we've had internally a few times.
Right now we have identified/started work across the following items:

• tooling and GH actions/workflows to perform automated accessibility audits on JLab, Retrolab, and possibly others. We will be adopting a similar pattern to that of the benchmarks tools
  https://github.com/jupyterlab/benchmarks
• reporting on the automated tests and manual tests
• a couple of extensions covering a accessible themes for JupyterLab (i.e. high contrast, monochrome, colour-blind friendly)
• a series of scripts that could be used for manual accessibility tests as we cannot solely rely on automated tests (the latter one might catch at most 30 percent of the accessibility issues)
• might be more to come...

As you can now imagine there is a mix of Python + JS dependencies, packages we will need to release and maintain and the such.
With such a diverse set of items (and outputs) being worked on it will be quite tricky to have all within a single repo, help others orient themselves about the purpose and the content of the repo, and at the same time we are also trying to adhere to the already existing patterns/conventions within Jupyter (i.e the cookie cutter for extensions). Having a mixture of everything but the kitchen sink will make it really hard for us to adhere to these conventions. Plus something we have painfully experienced as we worked on these items (over the last few months) is that getting the dependencies and the development environment right is very cumbersome and time consuming. And that complexity will only increase if we try and have multiple tools and packages within one repo. Ideally we'd prefer to keep that complexity at bay and lower the barrier for contribution. This is extremely important due to the multidisciplinary nature of the accessibility effort.

That covers much from the technical standpoint - but with accessibility being a sociotechnical system we are also doing work around documenting best practices, generating educational content, accessibility statements for the Jupyter tooling and more. So these items also deserve a space of their own where they will not be overshadowed or missed by being along with a bunch of developer tools.

Let me know if this helped clear this out a bit or feel free to come back with more questions.

[trallard]

Closing as we are tracking the compass items elsewhere #100