Skip to content

Conversation

@acharraggi
Copy link
Collaborator

I thought I'd change one page to see what the issues are and actually try a couple of screen readers.
JAWS on Windows, and a Read Aloud plugin in Vivaldi.

I did have a look at ADA compliance, but didn't actually run any compliance testers.
I found this a useful blog post about different compliance levels and a handy checklist.
https://www.civicplus.com/blog/wa/ada-compliance-checklist/

Quick Guide: ADA Compliance Checklist for Your Website
Step #1: Ensure Content has Appropriate Headings and Titles
Step #2: Use Text and Font to Benefit the Users
Step #3: Populate Tables
Step #4: Identify Visuals with Alternate Text
Step #5: Use Color Contrast
Step #6: Websites Need to be Navigable
Step #7: Don’t Use PDFs
Step #8: Enhance Your Multimedia
Step #9: Include “Skip Navigation” at the Top of Your Pages

I think many of our pages are "ok" with respect to those points, but alt tags and skip navigation will require a lot of work. Typically, it's not just the alt tag, you might be using the image instead of text, so you might need a whole paragraph.

Changes in the PR include ALT tag updates, rewording of some sections for clarity for a screen reader. Punctuation changes and removal acronyms not strictly required as screen readers will spell out the letters. Removal of the link to images as that adds cruft to be read by the screen reader and I don't think serves any useful purpose, it's not like these are thumbnail images in the page with a link to the full size image.

We have figure captions and Alt tags, which in theory means we should set alt=' ' (where there's a space character in the quotes) so the screen reads skips the alt tag since it will read the caption. Except Sphinx doesn't support alt=' ' (blank) and if you omit the tag some readers will read the link or image file name.
The suggestion I found was to use both but not repeat the alt text and caption text as a proper screen reader will read both.
Note: there are some “listen to this page’ browser features or extensions that skip over images and their alt tags entirely.

I added new descriptions that precede the field configuration images.

Watch for repetition: I also removed the "Note" that follows the Note heading. It was jarring to have that read aloud.

Note: ideally we should add 'skip navigation' to our pages. Some readers force the user to hear all the sidebar nav links. However, that's a Sphinx/ReadTheDocs theme issue that's mentioned in a couple of pull requests (one Sphinx, one RTD) but not resolved.

  • Title tag: remove “ — FIRST Tech Challenge Docs 0.2 documentation” from all titles.
    It is cruft that a screen reader has to read, it clutters the title for search engines, and probably gets truncated if the title gets too long. It adds no value I can see. Probably a theme change like skip navigation.

@acharraggi acharraggi marked this pull request as draft October 25, 2024 16:27
@acharraggi
Copy link
Collaborator Author

I just realised I didn't put these commits in a branch. I put the PR into draft. The whole ADA compliance thing probably needs discussion and decision about a guideline for how to do caption and alt tag text. Plus other easy ADA stuff like punctuation and acronyms. So we'll probably abandon this PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant