search

w3c / wcag3

WCAG 3
https://w3c.github.io/wcag3/guidelines/
Other
48 stars 11 forks source link

Update Explainer for 2024 #116

Closed iadawn closed 1 week ago

iadawn commented 2 months ago

This is a direct copy and bit of a clean from the baseline in https://github.com/w3c/silver/tree/main/explainer

netlify[bot] commented 2 months ago

Deploy Preview for wcag3-howtos canceled.

Name Link
Latest commit 591437e27374cb04faf0e38048b60bab3d6b5a1a
Latest deploy log https://app.netlify.com/sites/wcag3-howtos/deploys/672aa8fe679f6900089c4114
netlify[bot] commented 3 weeks ago

Deploy Preview for wcag3 ready!

Name Link
Latest commit 591437e27374cb04faf0e38048b60bab3d6b5a1a
Latest deploy log https://app.netlify.com/sites/wcag3/deploys/672aa8feb0b7bd000808ee47
Deploy Preview https://deploy-preview-116--wcag3.netlify.app
Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

rachaelbradley commented 3 weeks ago

Review requested by 5 November 2024

Please review the WCAG 3 Explainer (preview) and add suggested changes and comments to this Pull Request or google document before the 5 November 2024 AG meeting.

We will lock the google document 2 hours before the meeting and request all comments be submitted before that time.

alastc commented 3 weeks ago

In section 5.2, could we add a note such as: "The group is considering the addition of 'Recommendations' with the supplemental requirements, things which are good to do but may not be objectively testable."

lauracarlson commented 2 weeks ago

I added a couple of editorial comments in the Google doc.

detlevhfischer commented 2 weeks ago

Assertions may supplement Requirement to meet a Guideline. Not all Guidelines include Assertions.

This sentence is odd and even seems slightly ungrammatical. Regarding its substance: Does that mean to conform you need to meet the testable requirement in any case, and are free to add an assertion? Or does it mean you can meet a requirement (or just some requirements?) just by making an assertion? The text is not clear on that. If that lack of clarity is deliberate because the WG hasn't yet been decided whether or not a mere assertion can be deemed sufficient to meet a foundational requirement, this should be clearly stated.

It the meaning is that some requirements, due to the difficulty of testing them, can be met by an assertion but not others that can be tested, this should be clearly spelled out.

There is an empty bullet point in the Editor's note under 5.3.2 Documenting Assertions.

The AG has discussed also including recommendations which could help improve accessibility under guidelines.

This sentence feels wobbly. What does "accessibility under guidelines" mean? It's always about accessibility of content?

will include additional or more mature examples

not quite clear what is meant.

alastc commented 2 weeks ago

Hi @detlevhfischer,

Assertions may supplement Requirement to meet a Guideline. Not all Guidelines include Assertions. This sentence is odd and even seems slightly ungrammatical.

Would it be better as this? "An Assertion is another approach to meeting a Guideline. They do not replace Requirements, and not all Guidelines include Assertions."

Then you said:

Regarding its substance: Does that mean to conform you need to meet the testable requirement in any case, and are free to add an assertion? Or does it mean you can meet a requirement (or just some requirements?) just by making an assertion?

That's explained a little further down in section 7, where it says "Higher levels of conformance will be defined and met using Supplemental Requirements and Assertions."

So it's really down to the structure of the Foundational Requirements (baseline type things), then we've got the levels/percentages aspects above that.

The text is not clear on that. If that lack of clarity is deliberate because the WG hasn't yet been decided whether or not a mere assertion can be deemed sufficient to meet a foundational requirement, this should be clearly stated.

I think if you look at the intro to assertions, and the intro to the conformance model, does that make sense to you?

There is an empty bullet point in the Editor's note under 5.3.2 Documenting Assertions.

Thanks, I didn't see that in the preview, I'll check the code.

The AG has discussed also including recommendations which could help improve accessibility under guidelines. This sentence feels wobbly. What does "accessibility under guidelines" mean? It's always about accessibility of content?

Fair point, and combining with my point above, how about we remove that from the Assertions ednote, and add an ednote to the 5.2 Requirements and methods section? E.g. "The AG has discussed also including 'Recommendations' at the same level as Supplemental Requirements. Recommendations would be things which could help improve accessibility but may not be objectively testable. They could contribute to higher levels of conformance."

will include additional or more mature examples not quite clear what is meant.

The full paragraph is: "AG will continue developing requirements and methods. Each publication will include additional or more mature examples for public comment."

That just means will will iterate on the guidelines and keep publishing. Either more examples, or the examples will increase in their level of maturity. I'm not seeing a better way of saying that off-hand.

mraccess77 commented 2 weeks ago

Assertion is another approach to meeting a Guideline. They do not replace Requirements

These 2 phrases seem contradictory to me. I think what we are saying is that guidelines may necessitate either requirements and/or assertions be met. That could be a combination or requirement(s) and assertion(s) or requirement(s) or assertion(s) depend on the guideline. But what we aren't saying that instead of meeting a requirement you could make an assertion or vice versa (unless I misunderstand our approach).

alastc commented 2 weeks ago

Hi @mraccess77, we've made a few updates from the meeting, you can see them in this commit.

wareid commented 1 week ago

Very minor editorial/respec things, but it looks like a few words or terms are marked up as potentially having a glossary entry, but are not, so they get red squigglies underneath them:

Even if we don't have definitions yet it may be worth having the terms in the glossary with "TBD" next to them to get rid of the errors. There is also an error with the link for "Documenting Assertions" that goes nowhere, I am assuming because we don't have that document to link to, so it might be worth removing the reference or specifying it's coming soon.

alastc commented 6 days ago

@wareid I'm not sure if it was in this PR, but Kevin added those definitions.