-
-
Notifications
You must be signed in to change notification settings - Fork 32.9k
Add guidelines for accessibility in documentation #17340
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Add guidelines for accessibility in documentation #17340
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This looks pretty nice. I think there is value in adding this but I think this is advocating a bit too much for spreading stuff out in the docs rather than having a tightly focused a11y section.
FWIW I think there's value in both of these things but we should try to make sure anything dispersed throughout the rest of the docs are beginner-friendly and not confusing.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I agree that it's quite valuable to document accessibility considerations in the parts of the docs people are most likely to be seeing frequently – in references, alongside code examples, etc. – rather than cordoning them off into a separate accessibility page that people are unlikely to visit unless they are already interested in accessibility specifically.
I also think, to the point that @knyghty made, it would be helpful if we did make some of the example changes alongside this PR, and then we could point to them in the new docs here to give people a quick reference for how simple it can be to include accessibility considerations in the docs they are adding.
This comment was marked as outdated.
This comment was marked as outdated.
19fc11b
to
1844e5b
Compare
0a9ff63
to
c9ddf4e
Compare
Co-authored-by: Scott Cranfill <scott@scottcranfill.com>
c9ddf4e
to
c1c07e2
Compare
Now that #17338 is merged – updated this PR to simplify the proposed additions, and address all feedback so far. There is one point of feedback outstanding from @Scotchester:
I’m hesitant to proceed with this unless others agree this is the right think to do. Now handing over to @erosselli for review 🌈 |
Read the proposed changes as HTML. Builds upon #17338, adding guidelines specific to writing documentation. This is in the spirit of B.4.2. Ensure that documentation promotes the production of accessible content from the ATAG 2.0 standard.