Skip to content

Conversation

thibaudcolas
Copy link
Member

@thibaudcolas thibaudcolas commented Oct 5, 2023

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.

@thibaudcolas thibaudcolas requested a review from a team October 5, 2023 07:00
Copy link
Member

@knyghty knyghty left a 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.

Copy link

@Scotchester Scotchester left a 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.

@thibaudcolas

This comment was marked as outdated.

Co-authored-by: Scott Cranfill <scott@scottcranfill.com>
@thibaudcolas thibaudcolas force-pushed the accessibility-documentation-guidelines branch from c9ddf4e to c1c07e2 Compare July 26, 2025 10:36
@github-actions github-actions bot added the no ticket Based on PR title, no linked Trac ticket label Jul 26, 2025
@thibaudcolas
Copy link
Member Author

thibaudcolas commented Jul 26, 2025

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:

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.

I’m hesitant to proceed with this unless others agree this is the right think to do. Now handing over to @erosselli for review 🌈

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
no ticket Based on PR title, no linked Trac ticket
Projects
Status: In Progress
Development

Successfully merging this pull request may close these issues.

5 participants