Add page about accessibility docs #123

gabalafou · 2023-04-03T18:11:40Z

This PR addresses the problem that if you search the web for Jupyter-related accessibility docs, you are highly likely to end up at this repo because it tends to be in the top few results (at least whenever I search across various search engines). But this repo serves as the team compass for Jupyter Accessibility, not as a repo for end-user accessibility docs.

So this PR adds a page about the current state of accessibility docs and puts links to this new page in four highly visible places:

At the top of this repo's README
At the top of this repo's ReadTheDocs home page
At the top of the ReadTheDocs table of contents sidebar
At the top of the "Useful resources" page in the ReadTheDocs site

📚 Documentation preview 📚: https://jupyter-accessibility--123.org.readthedocs.build/en/123/

gabalafou · 2023-04-03T18:13:35Z

More needs to be done, but this is a start.

gabalafou · 2023-04-03T18:14:17Z

@steff456 (I don't know how to add you as a reviewer)

gabalafou · 2023-04-03T19:37:40Z

I think the links check is failing because I put the following URL in the repo readme:

https://jupyter-accessibility.readthedocs.io/en/latest/accessibility-docs

which doesn't exist until this PR is merged and triggers a ReadTheDocs deploy.

But there are some other failures or warnings in the log that I'm not sure about.

gabalafou

Done self-reviewing, now I need other people to review this PR :)

gabalafou · 2023-04-03T19:17:09Z

README.md

@@ -124,13 +124,13 @@ If you wish to manually build the documentation, you can use `conda` to do so.
 1. Create a `conda` environment to build the documentation.

   ```bash
-   conda env create -n accessibility-docs python=3.9
+   conda env create -n a11y-team-compass-docs python=3.9


I renamed the conda environment here and in other places to help avoid confusion. I was thinking somebody might skim this and think that these are commands for building end-user-facing accessibility docs

gabalafou · 2023-04-03T19:20:38Z

docs/index.md

@@ -32,10 +38,3 @@ Jupyter notebook Accessibility Statement
 ^^^
 **Coming soon**
 ````
-
-## Using Jupyter Software with Assistive Technology


I moved this info into the accessibility-docs page

gabalafou · 2023-04-03T19:20:51Z

docs/resources/useful-resources.md

@@ -12,9 +14,6 @@ guides, and documentation related to this:
 - [The tota11y toolbar](https://khan.github.io/tota11y/) is a lightweight javascript toolbar for quick a11y analysis.
 - [The WAVE tool](http://wave.webaim.org/report#/http://z2jh.jupyter.org/) is a web analyzer for page accessibility.

-## Jupyter a11y tech


Moved to accessibility-docs

gabalafou · 2023-04-03T19:22:24Z

docs/resources/useful-resources.md

@@ -1,5 +1,7 @@
 # Useful Jupyter Accessibility Resources

+Looking for [accessibility docs?](../accessibility-docs)


Wherever I removed the links to the a11y toolbar or the NVDA add-on, I added a link to accessibility-docs

Same comment as above

gabalafou · 2023-04-03T19:27:06Z

docs/index.md

+## Accessibility docs
+
+Looking for [accessibility docs?](accessibility-docs)
+


Maybe this should be an admonition of some kind but I'm not super familiar with MyST and I didn't want to spend too much time on this

Do we need to duplicate this one?

I think so yes because the goal for me with this PR is if somebody lands on one of our jupyter-accessibility pages after doing a search for Jupyter(Lab) accessibility - then I want to point them to the page I created in this PR.

The README.md file is shown in the front page of the GitHub repo, which is a high match in search engines for "jupyter" and "accessibility" - it's what you see at this URL: https://github.com/jupyter/accessibility

The index.md file is the front page for the team compass site, at this URL: https://jupyter-accessibility.readthedocs.io/en/latest/

I could potentially remove the pointer from useful-resources.md, but I think in that case we would need to restructure the organization of the team compass site. Because my concern with the current structure is that if someone lands on that page looking for VSCode-style user-facing accessibility docs, and they are trying to quickly locate something, their eye might land on "resources" and think that that's a match for what they're looking for, only to discover that it isn't. Because in this PR, I removed the link to the toolbar, the resources page after this PR only has resources that are mostly aimed at contributors or auditors.

Or are you asking something entirely different? Are you asking if there's a way to include a markdown snippet across several files, rather than copy-pasted the same content? That I don't know.

if i want to tab to the docs link, i'll have to tab through the header which seems like an unnecessary step.

i don't think that this should be heading. the call to action makes the most semantic sense as a link. an emoji like 🔔 would redirect peoples attention

Thanks @tonyfast looking out for this 😌. I changed it as you suggested

gabalafou · 2023-04-03T19:28:28Z

README.md

+## Accessibility Docs
+
+Looking for [accessibility docs?](https://jupyter-accessibility.readthedocs.io/en/latest/accessibility-docs)


I'm not 100% sure about this formatting or wording but I do like that it is short and to the point

I like it too

gabalafou · 2023-04-03T19:39:26Z

docs/accessibility-docs.md

@@ -0,0 +1,42 @@
+# Accessibility Docs
+
+If you are looking for accessibility docs[^1] for


Well this is annoying. When I build the docs locally, the footnote works, but when I look at this page on the ReadTheDocs preview build, it doesn't format the footnote: https://jupyter-accessibility--123.org.readthedocs.build/en/123/accessibility-docs.html

steff456

Thanks for doing this PR @gabalafou, I'm not sure if we need to add the message referencing the accessibility docs in every page or if we can just add it on the main page.

steff456 · 2023-04-05T19:59:04Z

README.md

+## Accessibility Docs
+
+Looking for [accessibility docs?](https://jupyter-accessibility.readthedocs.io/en/latest/accessibility-docs)


I like it too

steff456 · 2023-04-05T20:01:44Z

docs/index.md

+## Accessibility docs
+
+Looking for [accessibility docs?](accessibility-docs)
+


Do we need to duplicate this one?

steff456 · 2023-04-05T20:02:16Z

docs/resources/useful-resources.md

@@ -1,5 +1,7 @@
 # Useful Jupyter Accessibility Resources

+Looking for [accessibility docs?](../accessibility-docs)


Same comment as above

isabela-pf · 2023-04-10T16:36:29Z

docs/accessibility-docs.md

@@ -0,0 +1,42 @@
+# Accessibility Docs
+
+If you are looking for accessibility docs[^1] for


Maybe this is the standard format for reference links?

Suggested change

If you are looking for accessibility docs[^1] for

If you are looking for[accessibility docs] [1] for

isabela-pf · 2023-04-10T16:41:04Z

docs/accessibility-docs.md

+[^1]:
+    If you're not sure what accessibility docs are, we mean documentation
+    written specifically for disabled users. It should cover what features exist
+    in the software to help make it more accessible. Example: the [accessibility
+    docs for Visual Studio
+    Code](https://code.visualstudio.com/docs/editor/accessibility).


I'm less sure about this part. 😆 https://www.markdownguide.org/basic-syntax/#reference-style-links

Suggested change

[^1]:

If you're not sure what accessibility docs are, we mean documentation

written specifically for disabled users. It should cover what features exist

in the software to help make it more accessible. Example: the [accessibility

docs for Visual Studio

Code](https://code.visualstudio.com/docs/editor/accessibility).

[1]: If you're not sure what accessibility docs are, we mean documentation

written specifically for disabled users. It should cover what features exist

in the software to help make it more accessible. Example: the [accessibility

docs for Visual Studio

Code](https://code.visualstudio.com/docs/editor/accessibility).

I wasn't sure either, so rather than wrestle with the syntax, I cut the footnote and put it in parentheses at the end of the first paragraph.

steff456

As we discussed in our internal meeting today, this PR is ready to merge. Thanks for working in this @gabalafou!

Add page about accessibility docs

682e5f5

gabalafou requested review from trallard and isabela-pf April 3, 2023 18:11

gabalafou added 4 commits April 3, 2023 16:16

fix links, rename other references to 'accessibility-docs'

3e71616

make link checker happy

07a2a0f

try making the link checker happy (again)

208b87c

word wrap

dd3b377

gabalafou commented Apr 3, 2023

View reviewed changes

steff456 reviewed Apr 5, 2023

View reviewed changes

steff456 mentioned this pull request Apr 5, 2023

Team update - Apr 05, 2023 Quansight-Labs/jupyter-a11y-mgmt#206

Closed

isabela-pf reviewed Apr 10, 2023

View reviewed changes

Merge branch 'main' into accessibility-docs

a80e70c

isabela-pf reviewed Apr 10, 2023

View reviewed changes

move footnote

c9d7b24

steff456 approved these changes Apr 10, 2023

View reviewed changes

remove dangling footnote reference

ad54830

gabalafou merged commit f86e3e7 into jupyter:main Apr 11, 2023

gabalafou deleted the accessibility-docs branch April 11, 2023 14:30

steff456 mentioned this pull request Apr 13, 2023

Team update - Apr 12, 2023 Quansight-Labs/jupyter-a11y-mgmt#207

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add page about accessibility docs #123

Add page about accessibility docs #123

gabalafou commented Apr 3, 2023 •

edited

Loading

gabalafou commented Apr 3, 2023

gabalafou commented Apr 3, 2023

gabalafou commented Apr 3, 2023

gabalafou left a comment

gabalafou Apr 3, 2023

gabalafou Apr 3, 2023

gabalafou Apr 3, 2023

gabalafou Apr 3, 2023

steff456 Apr 5, 2023

gabalafou Apr 3, 2023

steff456 Apr 5, 2023

gabalafou Apr 6, 2023

tonyfast Apr 7, 2023

gabalafou Apr 10, 2023

gabalafou Apr 3, 2023

steff456 Apr 5, 2023

gabalafou Apr 3, 2023

steff456 left a comment

steff456 Apr 5, 2023

steff456 Apr 5, 2023

steff456 Apr 5, 2023

isabela-pf Apr 10, 2023

isabela-pf Apr 10, 2023 •

edited

Loading

gabalafou Apr 11, 2023

steff456 left a comment

		@@ -1,5 +1,7 @@
		# Useful Jupyter Accessibility Resources

		Looking for [accessibility docs?](../accessibility-docs)

		## Accessibility docs

		Looking for [accessibility docs?](accessibility-docs)

		## Accessibility Docs

		Looking for [accessibility docs?](https://jupyter-accessibility.readthedocs.io/en/latest/accessibility-docs)

		@@ -0,0 +1,42 @@
		# Accessibility Docs

		If you are looking for accessibility docs[^1] for

	If you are looking for accessibility docs[^1] for
	If you are looking for[accessibility docs] [1] for

Add page about accessibility docs #123

Add page about accessibility docs #123

Conversation

gabalafou commented Apr 3, 2023 • edited Loading

gabalafou commented Apr 3, 2023

gabalafou commented Apr 3, 2023

gabalafou commented Apr 3, 2023

gabalafou left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

steff456 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

isabela-pf Apr 10, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

steff456 left a comment

Choose a reason for hiding this comment

gabalafou commented Apr 3, 2023 •

edited

Loading

isabela-pf Apr 10, 2023 •

edited

Loading