Accessibility guidelines for all contributors #17338
Conversation
| ============= | ||
|
|
||
| All aspects of Django must be compatible with our accessibility standards, | ||
| and with the specific support targets we aim for. |
There was a problem hiding this comment.
It’s important to me we both provide authoritative standards, but those standards tend to be pretty far from enough to make things that work for real people. So this needs a clear acknowledgement.
|
|
||
| Django aims for conformance with `WCAG 2.2`_ at the AA level. | ||
| WCAG is the most well established standard for web accessibility. AA-level | ||
| guidelines are the most common legal compliance target around the world. |
There was a problem hiding this comment.
Technically speaking it’s WCAG 2.0 and 2.1 AA that are the most common legal compliance target. What's New in WCAG 2.2 is a good overview of the difference. It’s very negligible, as version 2.2 is fully "backwards compatible" with 2.1.
Source for "most common": https://www.w3.org/WAI/policies/.
|
|
||
| Wherever applicable, we also attempt to follow other best practices, such as: | ||
|
|
||
| * WCAG 2.2 AAA-level guidelines. |
There was a problem hiding this comment.
Including WCAG 2.0 and 2.1 AAA if this isn’t clear. All WCAG 2.0 / 2.1 guidelines are included in 2.2.
| Wherever applicable, we also attempt to follow other best practices, such as: | ||
|
|
||
| * WCAG 2.2 AAA-level guidelines. | ||
| * The upcoming `WCAG 3.0`_ guidelines. |
There was a problem hiding this comment.
They’re very far from being broadly applicable but I thought we might as well future-proof. Personally I would recommend following the drafts for contrast in particular, as WCAG 2.x contrast is notoriously poor.
|
|
||
| * WCAG 2.2 AAA-level guidelines. | ||
| * The upcoming `WCAG 3.0`_ guidelines. | ||
| * `ATAG 2.0`_ guidelines for authoring tools. |
There was a problem hiding this comment.
Not all are relevant but there’s lots in there that would help inform Django’s direction.
|
|
||
| * Touch-only navigation | ||
| * 400% browser zoom | ||
| * forced-colors mode DevTools emulation |
There was a problem hiding this comment.
This is my best attempt at distilling my usual accessibility testing practice to actionable bullet points. In the future, I could see ourselves wanting a more extensive checklist, with each item backed by third-party resources (for example https://www.magentaa11y.com/) – but we have to start somewhere.
| .. note:: | ||
| How much should you test? Devise the UI with accessibility in mind, | ||
| and the testing will only be needed as a final check. For more complex | ||
| interfaces, confer with other contributors to decide on testing targets. |
There was a problem hiding this comment.
Not sure this is totally needed. Again trying to provide reassurance that it’s ok if a contributor doesn’t feel like to spend lots of time testing if they’ve done some amount of research ahead of time.
There was a problem hiding this comment.
I agree that it's a worthwhile thing to include.
| Where expert help is available, also consider testing with: | ||
|
|
||
| * `JAWS`_ on Windows | ||
| * `Dragon`_ on Windows |
There was a problem hiding this comment.
These feel essential to me because they are very popular, but I chose to keep them separate because:
- Their licenses cost a lot of money
- They’re Windows-only
|
|
||
| Parts of Django do not meet our accessibility targets at the moment. | ||
| We actively work on fixing issues both as part of ongoing maintenance, | ||
| and bigger overhauls. To learn about known issues, and get involved, see: |
There was a problem hiding this comment.
I thought it was important to acknowledge that Django is quite far from meeting all the goals stated above (it’ll be plenty obvious to people going through the Django admin with our stated standards and testing targets in particular) – but that’s something we’re working on (and you can get involved 😉 ).
There was a problem hiding this comment.
Maybe a link to a board of open issues would be cool, such that possible maintaners can jump in
There was a problem hiding this comment.
There are links to open issues in items 2 and 3 in the list below, is that different from what you’re expecting?
|
Nice to see some a11y guidelines getting added to the docs 👍 I'm not an a11y expert so I've only commented on the grammar where it looks weird to me as a native english speaker. Side note: I'm a keyboard user and am super quick to notice when sites violate the keyboard-friendly parts of a11y… eg my pet hate is when devs take shortcuts by making div based buttons 🤯 I wonder if a note about how good a11y can benefit everyone? 🤔 |
|
Thanks for the review @shangxiao, much appreciated! That’s a great point re accessibility benefitting everyone, I’ll try to think a bit of where to add it in. |
There was a problem hiding this comment.
I think this is a great start.
One thing I want to mention is that I feel it's important to strike a balance between encouraging accessibility testing and making contributing easier as these seem like slightly conflicting goals. I think we should make it very explicit that if you are unsure about accessibility testing it's fine to - I'm not sure but e.g. tag the accessibility team on the PR and we can take a look for them.
I don't want these well-intentioned changes to deter anyone from contributing - especially to the admin which needs some love - because of the extra burden this adds.
| Accessibility standards | ||
| ======================= | ||
|
|
||
| Django aims for conformance with `WCAG 2.2`_ at the AA level. |
There was a problem hiding this comment.
"aims" feels like a bit of a cop-out, I'd prefer stronger language here.
There was a problem hiding this comment.
There's a tension that's hard to rectify: We definitely want to use strong language, but we also have to be honest about the fact that we're not there yet. In my suggestion on the intro above, I chose "We work … to …" as wording that indicates we are actively doing something, not just aiming/aspiring/seeking. Perhaps that sort of change would be good here, as well.
There was a problem hiding this comment.
I’ve tried to make this stronger, without making it sound like we’re there yet.
| a wide range of input devices and assistive technologies. | ||
| The best way to do this effectively is to take accessibility considerations | ||
| into account as part of designing features. If in doubt, consult | ||
| with users who rely on assistive technologies or with accessibility experts. |
There was a problem hiding this comment.
in the spirit of a "shift-left" approach.
What happened to not using technical jargon in documentation, Thibaud? 🤔
| a wide range of input devices and assistive technologies. | ||
| The best way to do this effectively is to take accessibility considerations | ||
| into account as part of designing features. If in doubt, consult | ||
| with users who rely on assistive technologies or with accessibility experts. |
| * Automated checks in the `Accessibility Insights`_ browser extension, | ||
| or an equivalent tool with the `Axe`_ checker. | ||
|
|
||
| Where appropriate, also test with: |
There was a problem hiding this comment.
I think we need to define (or at least give examples) when it's appropriate.
There was a problem hiding this comment.
Great idea, will do.
There was a problem hiding this comment.
Big +1, otherwise the "when" is subject to interpretation and subsequent potential frustration.
| We actively work on fixing issues both as part of ongoing maintenance, | ||
| and bigger overhauls. To learn about known issues, and get involved, see: | ||
|
|
||
| * ``#accessibility`` on the `Django Discord server`_. |
| Accessibility standards | ||
| ======================= | ||
|
|
||
| Django aims for conformance with `WCAG 2.2`_ at the AA level. |
There was a problem hiding this comment.
There's a tension that's hard to rectify: We definitely want to use strong language, but we also have to be honest about the fact that we're not there yet. In my suggestion on the intro above, I chose "We work … to …" as wording that indicates we are actively doing something, not just aiming/aspiring/seeking. Perhaps that sort of change would be good here, as well.
| .. note:: | ||
| How much should you test? Devise the UI with accessibility in mind, | ||
| and the testing will only be needed as a final check. For more complex | ||
| interfaces, confer with other contributors to decide on testing targets. |
There was a problem hiding this comment.
I agree that it's a worthwhile thing to include.
thibaudcolas
force-pushed
the
accessibility-guidelines
branch
from
e022dd5
to
9277b03
Compare
|
This is now ready for another round of review. Aside from specific edits, I have:
|
thibaudcolas
changed the title
thibaudcolas
changed the title
|
I believe we need feedback on those guidelines from a wider group than we have currently – so have created a forum thread and tweeted about this. I also uploaded the HTML version of those guidelines to help with reviews. The feedback so far has been excellent, but I’d like to hear from folks who haven’t been working in open source or on accessibility and whose contributions might be most impacted by those guidelines 💥🌈. Please share the forum thread or the tweet as you see fit! |
| for software and services that are used to produce web content. | ||
|
|
||
| To learn more about accessibility without diving straight into standards, | ||
| we recommend `The A11Y Project`_, a community-driven effort |
There was a problem hiding this comment.
An acronym definition of A11Y would be good here imo
There was a problem hiding this comment.
Hmmm interesting. Since this is the name of the website as they write it, I was hesitant to spell it out.
|
|
||
| Parts of Django do not meet our accessibility targets at the moment. | ||
| We actively work on fixing issues both as part of ongoing maintenance, | ||
| and bigger overhauls. To learn about known issues, and get involved, see: |
There was a problem hiding this comment.
Maybe a link to a board of open issues would be cool, such that possible maintaners can jump in
|
|
||
| Always test user interface changes with: | ||
|
|
||
| * Keyboard-only navigation |
There was a problem hiding this comment.
Is there some resource that we could link to that gives a checklist for what to cover here?
I can tab about, etc., but likely there’s lots that I wouldn’t think or know consider.
There was a problem hiding this comment.
Good point, yes definitely! The TL;DR; is you should be able to do everything with just tab, arrow keys, space and enter. There are some more nuances which a resource will be helpful for.
There was a problem hiding this comment.
I think this should link to a provided-by-us How-To.
There was a problem hiding this comment.
Circling back to this, and after having read the linked resources/references on the topic, I think that:
- The external resources are quite clear an educative about what "Keyboard-only navigation" is and how to test for it. 🥳
- The down side is that I haven't yet seen a resource that explains how to achieve it. Would you have a concrete example of a doc we would link to describing how to implement proper keyboard-only navigation?
|
Noting feedback I have received since the last call for feedback:
it seems tricky to me to add a link to the first paragraph as-is, and we’ve already spent lots of time refining its text, but we could certainly have a beginner-friendly link first before the one about standards
Agree 100% with this but I’m not sure what to do about it, as the main way I’d normally recommend writing those tests isn’t available in Django. It also feels like a specific enough point that it could be worth a separate PR or forum thread to discuss QA options. |
|
@thibaudcolas, maybe a callout (.. admonition, or similar) for the first point... 🤔
|
|
I see a Steering Council review was requested on this - I'm not enough of an accessibility expert to really review the content in deep detail, but is it just approval of the overall direction and tone that's wanted? |
|
Thanks for looking into this @andrewgodwin this forum thread might provide more context on what kind of feedback we need at this stage. TL;DR; is "overall direction" from the steering council. To be more specific – I think it would be interesting to get feedback along the lines of:
It’d also be interesting to hear from you on our approach here:
I don’t know how the steering council operates but if it helps I’m sure @django/accessibility would be keen to host a meeting to talk through the proposed guidelines and provide more context? |
Co-authored-by: Scott Cranfill <scott@scottcranfill.com> Co-authored-by: David Sanders <shang.xiao.sanders@gmail.com>
thibaudcolas
force-pushed
the
accessibility-guidelines
branch
from
9277b03
to
af737c0
Compare
|
@nessita 👋 this is waiting for your reply. I’ve updated to wrap at 79 characters or below everywhere, and address the points of feedback about specific instructions on when to test. Could you either take a look, or delegate this to someone else if you don’t have the time? In the meantime I have updated the guidelines’ HTML preview. |
Hey @thibaudcolas — the Fellows have a much higher workload than fits in the time available. Please be patient, and understand that pressure for an early review is unhelpful, and is a cause of stress. (There's plenty of that coming from folks who aren't high-visibility members of the community.) It's almost certain that @nessita has looked at this several times, and is just trying to find the mental space needed to reply appropriately. I understand you'll be keen to push this forwards, but she'll/they'll get to it in their time. Thanks 🙏 |
|
Hey @thibaudcolas, this review is on my to-do list, and as mentioned 4 days ago when you reached out on Slack, I intend to elevate its priority. It would be beneficial if you could provide additional context regarding the urgency and the need for repeated reminders. I still require a good chunk of uninterrupted time to thoroughly read the latest version of the doc and provide additional feedback. This is especially important because, in principle, I don't agree with one of the latest answers stating that How-Tos would not be included as part of our docs. To respond properly and constructively to that, I need to re-read the PR text, the associated links, and the external tutorials to feel comfortable that linking to external sites is a good experience for contributors. I hope that makes sense! 🤗 |
|
Thank you 🙏 I re-raised this because (to me) this is the top priority on the accessibility team’s list. Having this in place would help us in delegating reviews to people outside the team / just be faster at reviewing contributors’ pull requests and bug reports like https://code.djangoproject.com/ticket/35115. @nessita sorry if I’m annoying by reaching out on Slack and here – I just commented here because I hadn’t updated the PR when I raised this on Slack. I appreciate time is short for everyone but all we need here is a reply on "are how-tos really a must to merge this or not". If it’s yes, then we’ll figure out how to get the team working on those how-tos over 2024, and in the meantime publish those guidelines elsewhere. If it’s "no", then I can proceed with asking others here for review. |
Understood, thanks for the extra rationale.
That's the conundrum I face: my current response is I'm not sure. I do believe that internal how-tos are necessary, perhaps starting with a simple task, such as building a basic but accessible page using Django. However, given your strong stance that how-tos should link to external resources, I feel it's essential to invest time in reviewing those external resources. This way, I can better evaluate whether they fulfill the needs of Django users and contributors before potentially contradicting that approach. Would you please share a short list of the external how-tos that were considered for linking from the Django docs? |
|
Thanks! We haven’t considered any specific ones so far, but here are my go-to authoritative resources:
I expect we’d want to pick resources that work well for beginners, so if the external ones seem reasonable to you I might ask beginners to review them and give us their picks? Perhaps with a pre-triage by the accessibility team? For example here are the Keyboard resources: Perhaps others can share their thoughts too on what kind of resources would be most helpful in this context? |
|
Just reflecting on this a bit more – the docs suggested in #17340 would make for solid how-tos if we wanted to invest into our own. Everything on there is specific to Django. |
Hey @thibaudcolas, I'm a bit confused by this message, could you please expand a bit your thinking here? What docs specifically would be solid how-tos? Just in case the following is not widely known, the docs we add would ideally follow the Diataxis approach. |
|
@nessita what do you think is the path forward here? I think it's too onerous for us (at least for the moment) to maintain a lot of a11y documentation ourselves. The landscape changes very quickly as browsers add new features and assistive technology updates as well. I think at least in the medium term, linking to existing, well-researched external guides is preferable to having our own. Even if we were to maintain our own guides in the future (which would likely require expanding the a11y team considerably) I don't think these should block this PR. What do you think? |
Firstly, I'd appreciate hearing/reading others' views on this; I'd rather not be the sole decision-maker on whether to land this or not. Secondly, regarding my ask of "how-tos", I think I could provide some clarification to ensure we are talking about the same thing. For example, I read the links shared by @thibaudcolas, specifically the ones about keyboard navigation. The first one says: My worry is that, while the text emphasizes the importance of keyboard navigation, it doesn't provide practical guidance on how to achieve it. If a contributor proposes a PR and identifies that keyboard navigation is lacking, there should be clear instructions on what steps the contributor needs to take to address this. Essentially, if we're advocating for accessibility in PRs, my instinct is that we should also include explicit guidance on how to implement it (and likely the intro paragraph in this doc would reference the well known external sources describing the goal). Does this make sense?
I'm doubting if by guides we are talking about the same thing. I agree we should not (and can not possibly) maintain a whole set of docs about accessibility theory, but I think it would be beneficial to have some guides on how to achieve concrete things in Django related to a11y. A not accurate but perhaps helpful reference would be our CSRF docs, they do not explain the attack in detail, they reference well known sites (owasp, RFCs) if the user wants to know more, but we do provide a "How to use Django’s CSRF protection" to actually mitigate the attack in a Django site. In summary, if there are well known sites providing concrete/practical guidance on how to do the things we require, I think we could definitely make a compromise and push this forward. |
|
@nessita thank you for looking into this again, I’m still not clear if you’re talking about how-tos for Django contributors, or for developers using Django? I agree there’s value in providing accessibility how-tos for Django users like How to use Django’s CSRF protection, but that’s not really the point of this PR. If we’re talking about how-tos for contributors – I think we need to keep in mind here that currently we offer close to zero information for them to identify what’s important as far as accessibility. You mention the need for:
It seems to me like we have this already in the current draft ("conform to WCAG 2.2 AA", "confer with other contributors", "reach out to the Accessibility team for support"). There’s certainly room for us to link to more guidance for contributors with no accessibility experience working on their own. Contrary to what you said I think A11Y Project checklist – Keyboard is as practical as it gets, but if that’s not good enough we can spend more time working with our contributors to find better resources. I’d just like that process to not hold up what’s already pretty reasonable guidelines. |
I'm talking about how-tos (or similar, lightweight pages) for Django contributors. I only used the CSRF docs as an example of what I meant with describing theory vs practical guidance:
I agree. And this PR provides the guide for knowing what's important (I think there is no discussion about that).
While the current draft mentions "conform to WCAG 2.2 AA", "confer with other contributors", "reach out to the Accessibility team for support" there's a nuanced perspective on this. Requesting someone who is entirely new to accessibility to "conform to WCAG 2.2 AA" might feel like a daunting task. As someone who started as an accessibility novice, I can attest to the overwhelming and intimidating nature of such a request, particularly because the magnitude of the task is unclear. It might be beneficial to consider more approachable and gradual steps for contributors new to accessibility, ensuring a smoother onboarding process.
The link is very practical in terms of checking keyboard navigation, but it does not say how to fix something that does not allow for keyboard navigation. In other words: as a contributor, I open the link, I read "Can a person navigating with a keyboard or screen reader move around the page in a predictable way?", I try it, I can't do any useful nor predictive keyboard navigation, so the check fails. How can I fix it? That's the part that I think is missing (but necessary).
While I understand the importance of not delaying the landing of these (already reasonable) guidelines, I think I have a valid concern about the potential intimidation factor for contributors, particularly those new to the topic. Do you agree with that? |
|
I've been following the discussion here. I think some How-to(s) is/are needed I still look at the proposal and am at a loss as to What it means for me as a PR author or reviewer. There are a lot of links, which go to quite scary documents, from the sample I clicked. It feels like I have an awful lot to learn if I'm going to comply with the new guidelines. That's scary.
OK. But the must be some basics that cover the 80:20 and are to some extent eternal? Is that right? If so, could some worked examples/How-tos for those help? Perhaps with links to other resources ( The example from one of the reviews above was Keyboard navigation. OK, users should be able to do that. But what exactly counts as success there? I use tab a bit. I'm guessing though keyboard navigators do a bit more than that. But what? No idea. Not sure how to learn. (So not sure how to comply with the guidelines here.)
Does that exist? Would that be doable? |
|
I think we’re letting perfect be the enemy of good here :/ We have no accessibility guidelines for Django at all, even if just to state "Django aims to conform to WCAG 2.2 AA", which is the fundamental information that’s relevant to all contributors. Friendliness to new contributors is certainly a consideration, but I can’t imagine the status quo of "no docs at all" being any more friendly than what we’re proposing here.
In my opinion this is out of scope for Django accessibility guidelines. There is not much special about Django that would warrant having our own "how to implement keyboard support" documentation.
It is a very valid concern but I’d like to think we’ve done a reasonable job of helping with this by providing the right links. We’re recommending the A11Y Project and the Accessibility Insights browser extension specifically because they are beginner-friendly. @carltongibson yes, it’s a lot to learn. I think it’s reasonable for us to expect that people interested in contributing to UI in Django will either take the time to learn this, or defer to more experienced people, as appropriate.
We can certainly provide a link to test for keyboard navigation if we think that helps. I still think that the contributing docs stating "please make sure that keyboard navigation works" is better than the status quo. |
|
I'm confused. 🤔 Not a couple of comments ago you had a list of your go to resources, followed (a comment or two later) by some examples of good Django-specific cases where they could be shown in action. A how-to/tutorial/something showing what accessibility means in the context of a Django project, and how to check for that, on a PR to Django, or equally when you're working on your own project, would go miles here. And AFAICS is all that's needed. It's like any part of the contributing process: we have to document how it's done, so contributors (new and old) know what to do.
OK, here are the docs on setting up pre-commit. And so on.
Erm... — We need something to say here. The contribution docs aren't "perfect", but we can't just abandon folks here. (That wouldn't be "good" either.) I'm all for this endeavour but I read the PR again yesterday, and my take-away was that I wouldn't have clue where to begin. I'd have to spend a lot of time reading the linked resources, which is something I can do, but we need a Start Here!. (Or so I think.) |
|
Alright, I’ll do another draft where there’s a "start here" section at the top then? How does that sound to others? Maybe I can re-title Accessibility testing baseline to How to test accessibility in Django, and that will be the clearer beginner-friendly how-to? |
|
@sabderemane's post last week of her Accessibility checklist was right in the ballpark of what I think we need here. https://sarahabd.com/blog/my-accessibility-review-checklist I think we could either link to that or, if Sarah were OK with it, bring it in. |
|
@nessita @carltongibson I’d appreciate your thoughts on my last comment first, before we consider adding standalone "how-to" content as separate pages. If we can agree about the current single-page "contributor guidelines" model, with more beginner-friendly material and a "how-to test" section, I’ll work on another draft. If you think what we really need first and foremost is how-to material / accessibility checklists in the Django docs, I’ll close the PR and let other contributors have a go at that. |
|
@thibaudcolas for me (note emphasis) I like what you have here. My only addition would be a note at the top roughly saying, "If you're looking to get starting implementing these guidelines, see this How To/Tutorial over here". |
I think this is a good compromise. As Carlton said, with the recent article from Sarah A (which is so super helpful) and a smoother journey in the page from beginner friendly at the top -> more concrete and specific at the bottom, plus the now available Discord channel and Forum category, this would be a nice addition to our docs. @sarahboyce given your recent new role as fellow, would you have some time to review this proposal, perhaps after @thibaudcolas pushes a new revision, so you can share your view as well? |
|
Cool! On it |
Read the guidelines in HTML.
Introduces new guidelines as per discussions with @django/accessibility, and DEP-11 which formally created the team.
I chose to go with what I think is close to the most minimal set of guidelines possible. In particular,
I see a few issues with this as-is which I chose to leave unresolved for now, so we get something "live" and iterate on it later:
It did feel like the right place within the current setup based on how the "Work on the Django framework" docs are described.
Those docs as produced are heavily based on: