We should have links to glossary definitions in the SCs

[DavidMacDonald]

I was in the quick ref today about to click on a link to a glossary definition and realized there are no links in the SCs. Should probably have that.

[yatil]

Hi David, we deliberately decided to not add links to the page as it clutters the page visually and adds additional complexity to the page.

[DavidMacDonald]

Ohh! Hmmm... so the WCAG standard has a resource not available in the the quickref...

perhaps a future iteration could add on/off for linked glossary definitions in the settings. It's an important part of the WCAG, I'd say.

[jfhector]

I do believe that it is important to indicate that technical terms in Success Criteria are technical terms, and need to be interpreted is very specific ways. Links to the glossary would be the best way to achieve this.

Not having technical terms being indicated as such means that people get confused. I'm speaking from my colleagues' and my experience being confused with 1.4.3. and many other Success Criteria.

We can't assume that readers will click on the 'Understanding' link each time that they read a Success Criteria on the Quickref document. Or that they would think to read the Success Criteria again on the Understand page if they do click to it.

A concrete example: 'Large text' exception to 1.4.3

In the QuickRef document, the 'large text' exception to SC 1.4.3 reads like this:

"The visual presentation of text and images of text has a contrast ratio of at least 4.5:1, except for the following:

• Large Text: Large-scale text and images of large-scale text have a contrast ratio of at least 3:1;
• ... "

The term 'Large text' has a very specific meaning defined in the glossary. But in SC 1.4.3 in the QuickRef document, it is not identified as a technical term. This suggests that what constitutes 'Large text' is open to interpretation.

My colleagues' and my own failed attempts at understanding this Success Criteria have come in part from the fact that 'Large text' wasn't identified as a technical term.

Another concrete example: Technical terms in 1.2.3

1.2.3 uses five technical terms. Some of them don't mean much for someone who hasn't read the glossary.

It took me a long time to make sense of 1.2.3, because I was referring mainly to the Quickref document. When I did click through to the Understanding page, I didn't expect that I should read the Success Criteria again, as I had already read it in the Quickref document.

Without the links identifying technical terms, many of the Success Criteria are much harder to understand for beginners.

I think that the QuickRef document can be very useful to beginners. So I'm keen for others to use it without getting confused.

[jfhector]

I'd love to help, but I'm not familiar with Ruby nor Rails.

If I can help in another way, do let me know. (I know the WCAG, interaction design, usability testing, HTML CSS and JavaScript).

[yatil]

@jfhector Thanks, the issue is not ruby on rails (the templates in liquid are pretty straight forward), but the whole organization of content:

Extracting the content from WCAG, adding it to the JSON file, then adding the HTML to the page which probably would make it much larger (it already is quite large, 16.000 DOM elements :-D), so we would need to look into lazy loading parts which probably means rewriting the logic of how we sort.

And then you get to designer-y questions like how do we display those links, how do we enable that users keep their place in the document and not just get pointed to the bottom of the page with no way to get back.

It is quite a projects that involves many considerations through the whole stack :-)

The quickref is considered as a launch pad for digging deeper by using the other links on the page. I’ll suggest that we add some text into the “how to use” instructions that clarify that and keep this issue to enhance when/if we get resources to do so.

[jfhector]

I see. Thanks for helping me understand this better @yatil.