search

jupyter / accessibility

A repository for ongoing work around making Jupyter's software accessible and inclusive
https://jupyter-accessibility.readthedocs.io/en/latest/
BSD 3-Clause "New" or "Revised" License
65 stars 34 forks source link

ENH - Improve docs structure and update content #106

Closed trallard closed 1 year ago

trallard commented 1 year ago

Changes introduced:

  1. Simplify the documentation building requirements
  2. Document how to build the docs
  3. Restructure docs content - better sections and headings
  4. Update requirements
  5. Update logo
  6. Ensure meeting notes are rendered

Outstanding

Closes #105 Closes #47 It partially tackles #86

trallard commented 1 year ago

Ok I have removed the Draft status for the PR and verified that the PR previews are working 🎉 (to see them, you need to click on Show all checks > docs/readthedocs > details and this will open a new window so you can see the built docs).

@isabela-pf a review would be much appreciated - since this is a major refactor then any needed fine-grained details/improvements to sections/content.

I will fix the line breaks in this PR but that should be non-blocking I hope

choldgraf commented 1 year ago

Ah I believe that I no longer have maintainer access to this repository, so I cannot merge this PR. I think this is because @jasongrout removed me from the list of owners for the jupyter org. @jasongrout can you please add me back to this repository as an admin?

choldgraf commented 1 year ago

Also a couple quick thoughts on this PR:

trallard commented 1 year ago

Also a couple quick thoughts on this PR:

  • Looking at the structure of the site pages, I'm not sure who this documentation is for. Is it for others in the Jupyter ecosystem to learn about accessibility? Is it a way for us to provide accountability for the EOSS4 a11y project?

So these docs now cover a few scenarios:

  1. Go-to place for folks within Jupyter wanting to learn more about accessibility - need to add more resources here as the one suggested in #15
  2. Single point to learn about the "Jupyter-wide" accessibility initiatives and ongoing work - as we see it, the EOSS a11y project is for and by the Jupyter community (even if folks undertaking the work are in Quansight) - we decided from day 1 that we would work in the open and keep folks aligned on what is happening, changes in plans and treat the grant work as I mentioned before: for and by the community
  • Right now, the most prominent links to the left are about EOSS4...I feel these are probably not the most relevant ecosystem-wide links to display, compared with accessibility resources links etc. (though this depends on the answer to the above question).

I see - this can be misleading - I will move this to a lower level, maybe under "funded projects" or something of the such.

  • The "Join the Jupyter accessibility community" page is more like a list of previous accessibility workshops and resources rather than documentation about how to join. Maybe we can rename contribute to Contribute to Jupyter Accessibility, move it to the top of the section, and rename the current Contribute to... sections above under the Accessibility efforts section?

Good idea tbh this repo still needs a good reorg - right now my goal was to get the meeting minutes into the docs as everything was broken and Isabela had tried multiple times to add them to the TOC. And get those builds working again. The structure still needs plenty of work and some internal sections' content - but that can be done now in more minor PR's.

  • The EOSS4 roadmap could probably be two nested pages under a top-level page that describes the EOSS4 project in general, rather than two top-level pages. Agreed - this roadmap also needs updating (cc @isabela-pf as this has been something you've kept up-to-date in the past)
jasongrout commented 1 year ago

Chris: done!

trallard commented 1 year ago

I have made the reorg based on @choldgraf so now the grant work is under the "funded work" section.

I will get rid of the emojis tomorrow and merge then 🚀