Updating CG writing guidance with example removed from ACT format doc. #2156
Conversation
Jym77
left a comment
Jym77
left a comment
There was a problem hiding this comment.
Still nitpicking the "where to put exceptions" part 😅
I think that won't need a Call for Review. This is internal guidance, not normative text.
pages/design/rule-design.md
Outdated
| ### Subjectivity in Applicability vs Expectation Example | ||
|
|
||
| The below section contains 2 approaches for writing an ACT rule for testing text contrast. For each example, both the applicability and expectation are included for clarity. Each of these examples follows the ACT rules format, but note that in the first example, the applicability is ended with the phrase "... except if the test target is part of a text node that is purely decorative or does not express anything in human language", while in the second example this phrase is appended to the expectation. Both of these approaches follow the normative ACT rules format and lead to valid ACT rules; however, we recommend including this text in the applicability when possible. When phrases such as this are included in the applicability, some test cases become inapplicable that would otherwise be passed if the phrase was included in the expectation. For example, for a smiling face emoji would be considered inapplicable when using the approach in Example 1, while in Example 2 the smiling face emoji would pass since it is considered an exception to the expectation. |
There was a problem hiding this comment.
I'd rather favour a more blurry language as to where to put the exceptions.
I'm still not 100% sure that exceptions need to be in Applicability all the time, notably because WCAG criteria also have exceptions that feel better suited for Expectations.
Typically, 1.4.3 states:
The visual presentation of text and images of text has a contrast ratio of at least 4.5:1, except for the following:
(…)
Logotypes
Text that is part of a logo or brand name has no contrast requirement.
I agree that the SC doesn't care about "stuff that looks like text but actually isn't" (aka emoji), and thus these should not be applicable. It's less clear whether logotypes should be Inapplicable or Passing (and thus whether a "except if this is a logotype" part should be in Applicability or Expectation).
I'm having even stronger feeling for 2.5.5 where the "essential size" exception sounds like a Expectation one, not an Applicability one. So I'd say that pins on a map should be Applicable, and Passing. They are "targets for pointer input", so 2.5.5 is concerned about them, but give them a special "pass" due to their essential size. While Emojis are not "text [nor] image of text", thus 1.4.3 doesn't even care.
This gets even stronger with 2.5.8, where the minimal spacing is also listed as an exception, but I don't think it would make sense to have the rule apply to "clickable elements, except when they are spaced enough".
So, I totally agree that "exceptions (or any other logical parts) should be where they belong", but I think that "where they belong" can be either Applicability or Expectation, depending on the rule and the SC.
So, I'd favour a more blurry statement that we recommend using this text in the applicability where possible". It is more a matter of "we recommend using this text in the applicability when it makes sense".
But I'm not sure how to phrase this correctly… Maybe with a few more examples.
Maybe the questions that rule authors (and reviewers) need to consider is "if there was a page with only emoji, would I consider that 1.4.3 is relevant for it?", "if there was a page with only a map and clickable pins on it, would I consider that 2.5.5 is relevant for it?", … If the SC is relevant, then the logic should be in the Expectation, if it isn't then it should be in the Applicability.
Co-authored-by: Jean-Yves Moyen <jym@siteimprove.com>
carlosapaduarte
left a comment
carlosapaduarte
left a comment
There was a problem hiding this comment.
Some edits and a question to consider
pages/design/rule-design.md
Outdated
| Applicability describes which (elements of) web pages should be tested using the rule. These elements are known as test targets. Applicability must be written in plain language, as well-formed grammatically correct sentences, so that it can be used by QA testers. Applicability must rely on well defined properties of the technologies that are tested. For instance, a rule may be applicable to all `video` elements, but it can not be applicable to all `object` elements used to show video, unless the term "video" is further defined. | ||
|
|
||
| Use objective, unambiguous definitions within applicability. Finding objective definitions to use in rules can be difficult, if not outright impossible in some cases. The intent here is to ensure repeatability of the rule. Not everything in WCAG testing is entirely repeatable, but when it comes to rule applicability, this is a hard requirement. | ||
| The applicability of a rule must be unambiguous and should be written using objective statements and in plain language. Finding objective definitions to use in rules can be difficult, if not outright impossible in some cases. New in version 1.1 of the ACT rules format is the ability to write rules using a subjective applicability. For rules that include a subjectivity, it is preferred to include a list of features (either in line or as part of a definition) that describes how an element should be evaluated for matching the accessibility (see the "Styled as a Heading" example in the [ACT Rules Format: Applicability](https://www.w3.org/TR/act-rules-format/#applicability)). Additionally, in the past exception statements have been included in the Expectation that can be placed in the applicability, this is the recommended approach when possible (see the "Subjectivity in Applicability vs Expectation" example below). As a reminder, the intent here is to ensure repeatability of the rule. Not everything in WCAG testing is entirely repeatable, but when it comes to rule applicability, this is a hard requirement. |
There was a problem hiding this comment.
| The applicability of a rule must be unambiguous and should be written using objective statements and in plain language. Finding objective definitions to use in rules can be difficult, if not outright impossible in some cases. New in version 1.1 of the ACT rules format is the ability to write rules using a subjective applicability. For rules that include a subjectivity, it is preferred to include a list of features (either in line or as part of a definition) that describes how an element should be evaluated for matching the accessibility (see the "Styled as a Heading" example in the [ACT Rules Format: Applicability](https://www.w3.org/TR/act-rules-format/#applicability)). Additionally, in the past exception statements have been included in the Expectation that can be placed in the applicability, this is the recommended approach when possible (see the "Subjectivity in Applicability vs Expectation" example below). As a reminder, the intent here is to ensure repeatability of the rule. Not everything in WCAG testing is entirely repeatable, but when it comes to rule applicability, this is a hard requirement. | |
| The applicability of a rule must be unambiguous and should be written using objective statements and in plain language. Finding objective definitions to use in rules can be difficult, if not outright impossible in some cases. New in version 1.1 of the ACT rules format is the ability to write rules using a subjective applicability. For rules that include subjectivity, it is preferred to include a list of features (either inline or as part of a definition) that describes how an element should be evaluated for matching the accessibility (see the "Styled as a Heading" example in the [ACT Rules Format: Applicability](https://www.w3.org/TR/act-rules-format/#applicability)). Additionally, in the past, exception statements have been included in the Expectation that can be placed in the applicability. This is the recommended approach when possible (see the "Subjectivity in Applicability vs Expectation" example below). As a reminder, the intent here is to ensure the repeatability of the rule. Not everything in WCAG testing is entirely repeatable, but when it comes to rule applicability, this is a hard requirement. |
There was a problem hiding this comment.
Additionally, I'm not sure we should state "This is the recommended approach when possible". Wouldn't it be better to state "This is the recommended approach when the test subject is inapplicable, instead of artificially making it pass the rule by having the subjectivity in the expectation" (or just the shorter version "This is the recommended approach when the test subject is inapplicable")?
There was a problem hiding this comment.
This one seems to have gotten away from me. I have corrected to be a lot more clear in the newest version.
Adding suggestions from Carlos. Co-authored-by: Carlos Duarte <carlosapaduarte@gmail.com>
Co-authored-by: Giacomo Petri <giacomo.petri@usablenet.com>
✅ Deploy Preview for act-rules ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Updating writing guidelines documents with an example we originally had in the format but decided was better included in the writing guide. I haven't messed with these documents, so let me know if there is a better place to put the example than inline. I also don't know if this change requires a CFC, so let me know.
Need for Call for Review:
<< choose one of the following and remove the rest >>
<< check Process Document on Call for Review >>
This can be merged with 1 approval << choose reason: editorial changes to website/test code, adding new contributor, other (explain). >>
This will not require a Call for Review << choose reason(s): editorial changes (including to the applicability, expectation or examples section), changes to assumptions, background, accessibility support, change to website/test code (not rule), other (explain). >>
This will require a 1 week Call for Review << small changes affecting a small number of test cases, if in doubt do not use this. >>
This will require a 2 weeks Call for Review << new rule, or substantial changes affecting a large number of test cases, if in doubt, use this. >>
How to Review And Approve