feat: improvements on glossary a11y #34095

PassionPenguin · 2024-06-13T03:09:42Z

Description

improved links to keep consistent with other entries.

github-actions · 2024-06-13T03:11:09Z

Preview URLs

External URLs (13)

URL: /en-US/docs/Glossary/Accessibility_tree
Title: Accessibility tree

https://en.wikipedia.org/wiki/Web_accessibility (1 time) (Note! This may be a new URL 👀)
https://w3c.github.io/aria/ (1 time) (Note! This may be a new URL 👀)
https://webaim.org/ (1 time) (Note! This may be a new URL 👀)
https://www.w3.org/WAI/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Glossary/Accessibility
Title: Accessibility

https://developer.chrome.com/docs/lighthouse/accessibility/scoring (1 time) (Note! This may be a new URL 👀)
https://firefox-source-docs.mozilla.org/devtools-user/accessibility_inspector/index.html (1 time) (Note! This may be a new URL 👀)
https://w3c.github.io/aria/ (1 time) (Note! This may be a new URL 👀)
https://www.w3.org/WAI/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Glossary/Accessible_name
Title: Accessible name

https://en.wikipedia.org/wiki/Web_accessibility (1 time) (Note! This may be a new URL 👀)
https://w3c.github.io/accname/ (1 time) (Note! This may be a new URL 👀)
https://w3c.github.io/aria/ (1 time) (Note! This may be a new URL 👀)
https://webaim.org/ (1 time) (Note! This may be a new URL 👀)
https://www.w3.org/WAI/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2024-06-23 02:45:56)

hamishwillee · 2024-06-13T23:30:50Z

files/en-us/glossary/accessibility/index.md

@@ -6,7 +6,7 @@ page-type: glossary-definition

 {{GlossarySidebar}}

-**Accessibility** (**A11Y**) refers to best practices for keeping a website usable despite physical and technical restrictions. Web accessibility is formally defined and discussed at the {{Glossary("W3C")}} through the {{Glossary("WAI", "Web Accessibility Initiative (WAI)")}}.
+**Accessibility** (often abbreviated to **A11y** — as in, "a", then 11 characters, and then "y") in web development means enabling as many people as possible to use websites, even when those people's abilities are limited in some way. Web accessibility is formally defined and discussed at the {{Glossary("W3C")}} through the {{Glossary("WAI", "Web Accessibility Initiative (WAI)")}}.


Fly-by comment (meaning I choose not to arbitrate on this), but the format (**A11Y**) is a very well understood way of indicating contraction/short form of a word. I find "(often abbreviated to A11y — as in, "a", then 11 characters, and then "y")" as verbose with no added value.

many entries contains these abbreviations descriptions. this above was just copied from Web/Accessibility lol.

i totally agree with your point. l18n, l10n, ... this is a pretty common abbr way in computer science. maybe we can also remove Web/Accessibility's one.

I would argue that it might be a good thing to keep the verbose derivation of A11y in the Glossary for absolute beginners to web development. We can consider removing it from the Web/Accessibility page.

files/en-us/glossary/accessibility/index.md

dipikabh · 2024-06-18T21:39:17Z

Hi @PassionPenguin, thanks for this PR. To better understand the motivation, could you help explain the context for these changes and the reason for adding/deleting some of the links in "See also" across the three pages?

For example, I noticed that in files/en-us/glossary/accessible_name/index.md, links to [ARIA roles](/en-US/docs/Web/Accessibility/ARIA/Roles) and [ARIA attribute](/en-US/docs/Web/Accessibility/ARIA/Attributes) have been removed, and a link to the ARIA glossary page has been added instead.

Please check our "See also section" guidelines to see the recommended "Order of links" (that is, links to MDN pages before external links). Also check the broken links in https://pr34095.content.dev.mdn.mozit.cloud/en-US/docs/Glossary/Accessibility#see_also.

Let me know if you have any questions. We're more than happy to land improvements, but providing some context will help us understand and review them better.

files/en-us/glossary/accessibility/index.md

PassionPenguin · 2024-06-20T01:11:51Z

files/en-us/glossary/accessibility/index.md

+- [The W3C Web Accessibility Initiative (WAI)](https://www.w3.org/WAI/)
 - [Accessible Rich Internet Applications (WAI-ARIA)](https://w3c.github.io/aria/)


put WAI and WAI-ARIA together, given they are in the order of

WAI, the organization

WAI-ARIA, the spec put forward by the org

PassionPenguin · 2024-06-20T01:12:40Z

files/en-us/glossary/accessibility_tree/index.md

@@ -18,7 +18,7 @@ There are four properties in an accessibility tree object:
  - : How do we describe this thing, if we want to provide more description beyond the name? The description of a table could explain what kind of information the table contains.
 - [**role**](/en-US/docs/Web/Accessibility/ARIA/Roles)
  - : What kind of thing is it? For example, is it a button, a nav bar, or a list of items?
- **state**
+- [**state**](/en-US/docs/Web/Accessibility/ARIA/Attributes)


added link to attributes given aria-state is under attributes page right now

PassionPenguin · 2024-06-20T01:19:01Z

files/en-us/glossary/accessible_name/index.md

@@ -22,11 +22,21 @@ To create an association between visible content and an element or multiple text

 Many elements, such as sections of textual content, don't need an accessible name. All controls should have an accessible name. All images that convey information and aren't purely presentational do too.

-Assistive technologies will provide the user with the accessibility name property, which is the accessible name along with the element's role. While many elements don't need an accessible name, some content [roles](/en-US/docs/Web/Accessibility/ARIA/Roles) can benefit from having an accessible name. For example, a [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Roles/tabpanel_role) is a section of content that appears after a user activates the associated element with a [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) role. This role can be set on an element with no needed name, like the {{HTMLElement("div")}} element. The `tab` is the control and must have an accessible name. The `tabpanel` is the child (content section) of the `tab`. Adding `aria-labelledby` to the `tabpanel` is a best practice.
+Assistive technologies will provide the user with the accessibility name property, which is the accessible name along with the element's role. While many elements don't need an accessible name, it's necessary to provide accessible name to override or to supplement the content of an element with specified [roles](/en-US/docs/Web/Accessibility/ARIA/Roles). For example, a [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Roles/tabpanel_role) is a section of content that appears after a user activates the associated element with a [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) role. This role can be set on an element with no needed name, like the {{HTMLElement("div")}} element. The `tab` is the control and must have an accessible name. The `tabpanel` is the child (content section) of the `tab`. Adding `aria-labelledby` to the `tabpanel` is a best practice.


added some description of APG's recommendation on role-name

https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/#:~:text=Accessible%20Name%20Guidance%20by%20Role,-Certain%20elements%20always&text=Indicates%20how%20necessary%20it%20is,element%20with%20the%20specified%20role.

Co-authored-by: Dipika Bhattacharya <[email protected]>

PassionPenguin · 2024-06-20T01:27:19Z

Hi @PassionPenguin, thanks for this PR. To better understand the motivation, could you help explain the context for these changes and the reason for adding/deleting some of the links in "See also" across the three pages?

For example, I noticed that in files/en-us/glossary/accessible_name/index.md, links to [ARIA roles](/en-US/docs/Web/Accessibility/ARIA/Roles) and [ARIA attribute](/en-US/docs/Web/Accessibility/ARIA/Attributes) have been removed, and a link to the ARIA glossary page has been added instead.

Please check our "See also section" guidelines to see the recommended "Order of links" (that is, links to MDN pages before external links). Also check the broken links in https://pr34095.content.dev.mdn.mozit.cloud/en-US/docs/Glossary/Accessibility#see_also.

Let me know if you have any questions. We're more than happy to land improvements, but providing some context will help us understand and review them better.

Thx for your kindly reviews!

a. links are reverted (while i still consider is it necessary to open up a new page on discussing too detailed computation and recommendation provided by WAI accname and WAI-APG)
b. links order. that have been discussed before, as i made several changes to make links better, though, some reviewers thought that order of links are just recommendation but not stereotype for writer to create better articles. in this case, accname are closely related to accessible name (as that's the spec concentrating on accessible name's implementation and computation) ref
c. i have added motivations per changes! sorry for not providing them in time

dipikabh

Hello @PassionPenguin, thanks for taking the time to explain the reason for adding the links. I was mostly looking for an overall context for the changes. Perhaps in the future, filling in the PR template questions could help.

I apologize for the mixed messages from reviewers about the order of links in "See also". I have a different opinion but will let it go.

I've left a few suggestions in the rest of the text. Thanks a lot for your contributions.

files/en-us/glossary/accessibility/index.md

dipikabh · 2024-06-20T21:17:21Z

files/en-us/glossary/accessibility/index.md

 - [Web Accessibility In Mind](https://webaim.org/)
+- [Glossary](/en-US/docs/Glossary)


I noticed a different style has been adopted here: #33423 (comment), and I understand you might have already implemented it on many pages, so I won't ask you to revert it.

However, to keep the list (and the page length) contained, I would have formatted this as (no link on Glossary):

For one term in in the list:

Related glossary terms: <term 1 link>

For multiple terms:

Related glossary terms: <term 1 link>, <term 2 link>

FWIW I would have personally gone with

<term 1 link>

<term 2 link>

Without any extra text, per see also guidelines, but I have no feelings towards any of them.

FYI, i have been translated pages under glossary folder for some time (processed about 300-350 files and PRs), and find that in most cases they are arranged in that style, and with suggestion from @bsmth, using the style of the most common case but without a link, i.e.

- Glossary - a. - b.

files/en-us/glossary/accessibility/index.md

files/en-us/glossary/accessible_name/index.md

Co-authored-by: Dipika Bhattacharya <[email protected]>

dipikabh · 2024-06-26T17:21:17Z

This can be merged. Keeping it open for a short time in case we want to apply changes similar to #34165.

bsmth · 2024-06-27T09:05:05Z

This can be merged. Keeping it open for a short time in case we want to apply changes similar to #34165.

Thanks a lot! I also think the changes look good, with one comment that I think linking to /Glossary is not necessary, so I would just prefer not to do this:

- [Glossary](/en-US/docs/Glossary)
  - {{Glossary("Term1")}}

And do this instead:

- Glossary
  - {{Glossary("Term1")}}
  - {{Glossary("Term2")}}

Or indeed

- {{Glossary("Term1")}}
- {{Glossary("Term2")}}

dipikabh · 2024-06-27T12:11:14Z

linking to /Glossary is not necessary

Agree. I think we can do a batch update for all such instances (I see around 40) in a new PR, and land this one for now.

I would prefer the following:

- Related glossary terms:
  - {{Glossary("Term1")}}
  - {{Glossary("Term2")}}

Reasons:

There is a colon missing at the start of the list.
We need to qualify "Glossary" slightly considering we're already on a glossary page.
It would be nice to say upfront before the list that the links are glossary terms and not guide or reference pages (so not the last suggestion).

dipikabh

Thanks a lot, @PassionPenguin

feat: improvements on a11y glossary entries

c48579d

PassionPenguin requested a review from a team as a code owner June 13, 2024 03:09

PassionPenguin requested review from dipikabh and removed request for a team June 13, 2024 03:09

github-actions bot added the Content:Glossary Glossary entries label Jun 13, 2024

PassionPenguin mentioned this pull request Jun 13, 2024

#33034: accessible description #33929

Merged

github-actions bot added the size/s [PR only] 6-50 LoC changed label Jun 13, 2024

PassionPenguin added 2 commits June 13, 2024 03:31

fix: macro

5799abb

feat: improvements

1c6e3ce

PassionPenguin changed the title ~~feat: improvements on a11y glossary entries~~ feat: improvements on glossary a11y Jun 13, 2024

feat: links

7b15162

github-actions bot added size/m [PR only] 51-500 LoC changed and removed size/s [PR only] 6-50 LoC changed labels Jun 13, 2024

fix: macro

e9a0e57

hamishwillee reviewed Jun 13, 2024

View reviewed changes

PassionPenguin added 2 commits June 14, 2024 11:17

feat: improvements

828bdc4

revert: aria

a1b332d

github-actions bot added size/s [PR only] 6-50 LoC changed and removed size/m [PR only] 51-500 LoC changed labels Jun 14, 2024

dipikabh reviewed Jun 18, 2024

View reviewed changes

files/en-us/glossary/accessibility/index.md Outdated Show resolved Hide resolved

PassionPenguin commented Jun 20, 2024

View reviewed changes

feat: improvements

e19f19f

PassionPenguin commented Jun 20, 2024

View reviewed changes

PassionPenguin and others added 2 commits June 20, 2024 09:19

revert

cccf6dc

feat: improvements

90fdb13

Co-authored-by: Dipika Bhattacharya <[email protected]>

dipikabh requested changes Jun 20, 2024

View reviewed changes

feat: improvements

3cef4ce

Co-authored-by: Dipika Bhattacharya <[email protected]>

PassionPenguin requested a review from dipikabh June 25, 2024 10:15

bsmth approved these changes Jun 27, 2024

View reviewed changes

dipikabh approved these changes Jun 27, 2024

View reviewed changes

dipikabh merged commit ad2f2bb into mdn:main Jun 27, 2024
8 checks passed

PassionPenguin mentioned this pull request Jun 27, 2024

improvements on glossary links in see-also #34451

Closed

PassionPenguin deleted the a11y branch June 27, 2024 12:43

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: improvements on glossary a11y #34095

feat: improvements on glossary a11y #34095

PassionPenguin commented Jun 13, 2024

github-actions bot commented Jun 13, 2024 •

edited

Loading

hamishwillee Jun 13, 2024

PassionPenguin Jun 14, 2024

dipikabh Jun 18, 2024

dipikabh commented Jun 18, 2024

PassionPenguin Jun 20, 2024

PassionPenguin Jun 20, 2024

PassionPenguin Jun 20, 2024

PassionPenguin commented Jun 20, 2024

dipikabh left a comment

dipikabh Jun 20, 2024

Josh-Cena Jun 20, 2024

PassionPenguin Jun 23, 2024

dipikabh commented Jun 26, 2024

bsmth commented Jun 27, 2024

dipikabh commented Jun 27, 2024 •

edited

Loading

dipikabh left a comment

		- [The W3C Web Accessibility Initiative (WAI)](https://www.w3.org/WAI/)
		- [Accessible Rich Internet Applications (WAI-ARIA)](https://w3c.github.io/aria/)

		- [Web Accessibility In Mind](https://webaim.org/)
		- [Glossary](/en-US/docs/Glossary)

feat: improvements on glossary a11y #34095

feat: improvements on glossary a11y #34095

Conversation

PassionPenguin commented Jun 13, 2024

Description

github-actions bot commented Jun 13, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dipikabh commented Jun 18, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

PassionPenguin commented Jun 20, 2024

dipikabh left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dipikabh commented Jun 26, 2024

bsmth commented Jun 27, 2024

dipikabh commented Jun 27, 2024 • edited Loading

dipikabh left a comment

Choose a reason for hiding this comment

github-actions bot commented Jun 13, 2024 •

edited

Loading

dipikabh commented Jun 27, 2024 •

edited

Loading