Accessibility should be more prominent on CSS/HTML element pages

[hkolbeck]

Per the element page template, accessibility concerns are towards the bottom of the page, just above the technical summary: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/HTML_element_page_template#accessibility_concerns

It seems likely that most readers would never make it that far down the page, and so miss the fact that they could be making the web less accessible. I would propose moving it to just above attributes See below for revised proposal. This was spurred by this example: mdn/content#28189

There's definitely a few, but it doesn't seem like an unconquerable number:

~/Code/MDN-content/files/en-us/web/html/element main
❯ grep -Ri "## Accessibility concerns" * | cut -f1 -d/
abbr
audio
br
button
canvas
datalist
del
div
dl
embed
footer
heading_elements
hgroup
html
iframe
img
input
ins
label
main
mark
output
p
portal
pre
progress
s
table
title
video

Edit: After some discussion below, I would advocate the following steps:

1. Move current "Accessibility concerns" sections to just above "Examples", rename them "Accessibility"
2. Place an alert box at the top of the page with any warnings deemed important, discussion of what "important" means can wait.
3. If there's an accessibility issue with a specific attribute, include an alert box next to it with necessary information

The intent is to alert both linear readers and ctrl-f developers to any critical issues, with easy to find and consistently placed documentation on more general accessibility questions.

[jpluimers]

+zillion

Especially with WCAG 2 becoming mandatory in more places, giving accessibility information a more prominent place is really important.

(accessible web-sites are not just good for people that need it: it improves them for everybody; I know that @hkolbeck knows this, but many others still need to be educated on this)

[hkolbeck]

I've done an initial first go. I'd intended to just do a local PR, but c'est la vie, it's done, no reason to undo it. mdn/content#28201

Edit: Closed, see https://github.com/orgs/mdn/discussions/430#discussioncomment-6562096 for discussion

[chrisdavidmills]

@hkolbeck I totally agree with you that the Accessibility concerns should be as prominent as possible. I do think that before doing any more work on changing the position of them all, we should get a consensus on if and where to move them, to avoid wasting your precious time.

In my experience, MDN readers tend to look at the top and bottom of pages, and the examples. They want a description of what x does, they want to look at the compat data to see if they can use it in their project, and they want to grab an example to copy and paste into their code editor. Anything in the middle of the page is most likely to get overlooked.

Also, note that a lot of CSS pages have Accessibility concerns sections too; they would also need changing.

This all said I think higher up is probably better for these in terms of visibility. They should definitely be above the technical summary stuff, as that is seldom looked at.

I think that above the "Examples" section would be the best place — it is important fundamental information to know when using the feature, but I feel that the attributes the element can have applied to it is more fundamental and should be higher up. It also makes sense from a learning flow perspective.

[chrisdavidmills]

You've got some good ideas here. I think that, once we get a consensus, this is the sort of project that would be ideal for community members like yourself to chip away at and get done over time. Most of the regular MDN writers regard a11y as very important, but there are so many things to do. New feature content takes up a lot of our time.

I think we originally decided on "Accessibility concerns" as a way to make the information sound more urgent. "Guidelines" sounds a bit wishy washy in that content, kind of "take it or leave it". I think "Accessibility" sounds like a good title.

It would maybe be good for you to update a page to show the latest structure you are proposing, with an example of the alert box for areas of high concern.

as someone just joining this community I feel ill equipped to lead it

Yeah, no one would expect you to do so, although you should totally feel empowered to start bugging people until you get answers. We are a pretty friendly bunch.

As someone who has been around MDN for a long time, I'm more than happy to give you some guidance on how to move forward with this.

[hkolbeck]

I appreciate the feedback, and I hope we can work towards that consensus.

I want to push back on:

this is the sort of project that would be ideal for community members like yourself to chip away at and get done over time. Most of the regular MDN writers regard a11y as very important, but there are so many things to do. New feature content takes up a lot of our time.

Favoring new features over a11y work is the heart of why the web is so inaccessible. I realize why it's that way, I've been a corporate developer, but that doesn't mean you can't push back on that prioritization. Always pushing a11y work onto the community is not a sign that you value it. I'm truly not trying to start a fight, but this is a common refrain and I find it immensely frustrating.

[chrisdavidmills]

I totally agree with you, and understand why my statement sounds bad. It is also about prioritization too. The change we are discussing here is great because it has a chance of making useful accessibility knowledge easier to find. If we were talking about something a bit more critical (e.g. the content is completely inaccessible, or we need to make a significant change to the site to make pages more accessible in general), that would be given a higher priority than new content.

And it is not fair to say that we are always pushing a11y work onto the community. I said that this would be an ideal community project because it can easily be split up into small bite-sized chunks that are doable by someone who wants to contribute but only has limited time to do so, not because it is accessibility-related.

Consider also that the new content work we do is carefully done to be as accessible as possible — for example, we carefully consider the language we use, and make sure the code examples we include are written with a11y best practices in mind.

[hkolbeck]

it is not fair to say that we are always pushing a11y work onto the community

You're right, I expressed some more general frustration with tech directed at you, and that wasn't fair. I'm sorry.

[chrisdavidmills]

You're right, I expressed some more general frustration with tech directed at you, and that wasn't fair. I'm sorry.

Hey, no worries. I can totally understand where that frustration comes from. I've experienced it myself more than once!

[Josh-Cena]

I agree with @chrisdavidmills that this should be above "Examples". I don't know why we have both "Usage notes" and "Accessibility concerns" when the latter is a subset of the former, but I'm okay to put the latter before the former if that's more visible. However it should definitely be below "Attributes" and "Events", because these are indispensable parts to understanding how the element works at all, while "Accessibility concerns" just provides more context about proper usage. "Accessibility concerns" may also make references to certain attributes (like "do not use autofocus"), and it would be jarring if autofocus hasn't been introduced yet.

[hkolbeck]

You're ignoring the proposal I put forward, which I think addresses this.

[chrisdavidmills]

To just jump in here, I think what both of you are saying has merit, and actually I think your thoughts are moving in the same direction. I totally agree with Josh's thought's on the process of understanding, and the positioning of the Accessibility sections as a result, but Hannah's proposal in https://github.com/orgs/mdn/discussions/430#discussioncomment-6562208 is compatible with that.

[hkolbeck]

I can accept that I'm coming at this from perhaps a different place than most, as my usage pattern of the site is Open -> Ctrl-F $attribute-I-need -> Read -> Close and I don't know how common that is. With that usage, the linear flow you're talking about doesn't factor in, and accessibility concerns that are not either called out at the top of the page or next to the affected subsection won't be noticed. I agree that putting the entire section at the top introduces a lot of usage before explanation, and am not really advocating for that.

[chrisdavidmills]

my usage pattern of the site is Open -> Ctrl-F $attribute-I-need -> Read -> Close and I don't know how common that is

@hkolbeck this is hugely common — "Ctrl + F developers", as we call you ;-) This is probably the most common pattern for experienced devs using the site as pure reference material. Saying that, there is also value in optimizing the order for folks who favor a more linear pattern of parsing.

[hkolbeck]

Knowing that, it might be worth considering alert-formatted warnings next to the docs for attributes with major accessibility implications, though nothing comes immediately to mind that that would apply to. A candidate is alt on <img> but that's a different beast than I'm talking about, I'm thinking more "If you use this attribute you need to be conscious of <blank>".

[joelanman]

I think this is a good example:

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/number#accessibility

type="number" is often misused as its intended for a very specific case, and even then has significant accessibility and usability issues. The warning here comes after a large amount of content.

In the GOV.UK Design System, we have a prominent section at the top about usage that covers advantages and disadvantages, and in extreme cases recommends against usage. That may or may not be something you can do here, but I'm linking it as an example:

https://design-system.service.gov.uk/components/select/

[hkolbeck]

I would advocate the following:

• Move current "Accessibility concerns" sections to just above "Examples", rename them "Accessibility"
• Place an alert box at the top of the page with any warnings deemed important
• If there's an accessibility issue with a specific attribute, include an alert box next to it with necessary information

The intent is to alert both linear readers and ctrl-f developers to any critical issues. I realize that's a lot of work and won't happen overnight, but I'm willing to do the initial work of just moving and renaming sections.

Edit: I'm volunteering to do the initial move for the HTML element pages, is anyone willing to take on the CSS pages?

[hkolbeck]

That was my thought as well. I'm volunteering to do that initial move, the finer details can come later.

[Josh-Cena]

Sounds like a plan to me!

[chrisdavidmills]

+1: I support this plan as well, and am happy to act as a reviewer and provide guidance.

[hkolbeck]

I'd like to start with a PR just touching the template, does it seem worth starting that work?

[chrisdavidmills]

Yup, sounds worthwhile. That way anyone looking at the template for guidance on the structure for a new page doesn't end up creating another page with a wrong structure that you then have to fix.

[hkolbeck]

Update: I'm afraid my life went a bit sideways last month, and I'm just starting to recover. I hope to return to this soon, but if anyone is willing to take on the template reshuffle, it would be so appreciated

[bsmth]

Hi @hkolbeck, thanks for letting us know - I hope your recovery is going well. I'm sure someone from the team would be happy to pick up the template work in the meantime. Please take your time and feel free to let us know if you'd like to pick up related work again at any point 🙏🏻

[hkolbeck]

Further update: I recently found why I was running into issues with this and related projects, and unfortunately the answer is brain cancer. I'd like to boost this, as I think it's important, and will also be seeking folks elsewhere who could be interested in helping 💜

[hkolbeck]

Further further update: I had a large brain tumor removed about two weeks ago and am doing better than ever expected in many ways. Unfortunately it has left me permanently unable to do the kind of work I see needed here. I hope that others can take it on, and I will continue seeking folks willing and able.

[elichad]

Hello, thanks @hkolbeck for pushing forward this discussion and for signal boosting recently. I'd like to pick this up, starting with a PR to improve the HTML element page template as suggested.

(Note I don't have the technical knowledge to review all the content in these accessibility sections, I'll focus just on moving said content)

[dipikabh]

Hi everyone, I'd like to chime in on this discussion. Thanks @hkolbeck for raising it; this is indeed an important topic, and I completely agree with moving the accessibility section before "Examples" on HTML element pages (and probably after "Description" on CSS property pages).

I have some remarks about renaming the section though. To me, the section name "Accessibility" on its own seems a bit incomplete; it seems to need an adjective to clarify what aspect of accessibility, related to the current element or property, this section is addressing. To strike a balance between calling it "Accessibility concerns" (since not all such sections present the content as concerns or issues) or "Accessibility guidelines", I would suggest calling it "Accessibility notes" to cover concerns, warnings, guidelines, best practices, and so on. Alternatively, I also quite like "Accessibility guidelines" as an over overarching option.

When we update the HTML element page and CSS property page templates, apart from the name and position changes, we'll also need to update the description of the section to align with the new name ("Accessibility" or "Accessibility notes" or something else). At the moment, the section refers to "potential accessibility concerns", but we need to widen its scope to include guidelines and best practices as well (essentially, not focusing on just "concerns").

[hkolbeck]

I did think a bit about additional wording, and felt that simply "Accessibility" was best because the type of documentation following was so diverse. I think any word broad enough to cover possible content will soften the importance of the underlying docs, and while I don't think the lone word is perfect by any means, I do think it's the best available. If additional context is needed I think sub-section titles are the best approach, especially given how many pages will have both warnings and best practices, for instance.

All that said, this is very much a disagreement on details. I appreciate your thought and pushing on this so much 💜

[elichad]

Personally, adding "notes" to the end diminishes the importance in my mind - I typically expect "notes" to contain extra detail for interested parties only, and I don't expect them to contain important information about how something should be used that might require me to make significant changes.
I don't mind "Accessibility guidelines" as I think that can encompass both concerns and best practices, but I also think just "Accessibility" is best, especially in conjunction with sub-section titles as @hkolbeck suggests.

[dipikabh]

Thank you both for sharing your thoughts on the suggestion. I agree, deciding on the name for the section is not a blocker for making the other changes. We can always revisit and revise the name if there is consensus and a strong need to do so. Let's then proceed with "Accessibility" for now. FWIW, I am more inclined towards using "Accessibility guidelines".

@hkolbeck, hope you're recovering well and doing better 🤞.

[hkolbeck]

@dipikabh much appreciated. I'm faring much better than expected in many ways, and am quite happy about it, but unfortunately many disabilities are permanent and have most likely removed my ability to help here beyond discussion 😕

[dipikabh]

No worries, we have a great team and community who will be able to see this through in action. Take care and all the best.