Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DRAFT: Subjective applicability #539

Closed
wants to merge 5 commits into from
Closed

DRAFT: Subjective applicability #539

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
43ce209
Subjective applicability draft.
tbostic32 Jul 25, 2023
9b840ac
Update act-rules-format/act-rules-format.bs
tbostic32 Aug 23, 2023
ddbce11
Adding glossary definition features.
tbostic32 Aug 23, 2023
c8b05a9
Update act-rules-format/act-rules-format.bs
tbostic32 Aug 23, 2023
d9cc98a
Merge branch 'w3c:main' into tbostic/subjective_applicability
tbostic32 Dec 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 24 additions & 3 deletions act-rules-format/act-rules-format.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -408,11 +408,18 @@ The applicability describes what parts of the [=test subject=] are tested.

### Applicability for Atomic Rules ### {#applicability-atomic}

The applicability section is a required part of an [=atomic rule=]. It <em class="rfc2119">must</em> contain a precise description of the parts of the [=test subject=] to which the rule applies. For example, specific nodes in the DOM [[DOM]] tree, or tags that are incorrectly closed in an HTML [[HTML]] document. These are known as the [=test targets=]. The applicability <em class="rfc2119">must</em> only use information made available through the listed [input aspects](#input-aspects) in the rule. No other information can be used in the applicability. Applicability <em class="rfc2119">must</em> be described objectively, unambiguously and in plain language.
The applicability section is a required part of an [=atomic rule=]. It <em class="rfc2119">must</em> contain a precise description of the parts of the [=test subject=] to which the rule applies. For example, specific nodes in the DOM [[DOM]] tree, or tags that are incorrectly closed in an HTML [[HTML]] document. These are known as the [=test targets=]. The applicability <em class="rfc2119">must</em> only use information made available through the listed [input aspects](#input-aspects) in the rule. Definitions used in the description can be put in the rule [glossary](#glossary), or they can be defined in the section where they are used. No other information can be used in the applicability.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As an aside, I think we should remove the

tags that are incorrectly closed in an HTML document

wording, since this refers to 4.1.1 which is getting deprecated in 2.2.


An objective description is one that can be resolved without uncertainty, in a given technology. Examples of objective properties in HTML are tag names, their computed role, the distance between two elements, etc. Subjective properties on the other hand, are concepts like decorative, navigation mechanism and pre-recorded.
Applicability <em class="rfc2119">must</em> be written unambiguously and in plain language. Applicability <em class="rfc2119">must</em> either be described objectively or use an **allowed subjective form**. An objective description is one that can be resolved without uncertainty, in a given technology. Examples of objective properties in HTML are tag names, their computed role, the distance between two elements, etc. When possible, objective descriptions <em class="rfc2119">should</em> be used since they reduce uncertainty.

Even concepts like headings and images can be misunderstood. These terms could refer to the tag name, the semantic role, or the element's purpose on the web page because they are ambiguous. The latter of which is almost impossible to define objectively. When used in applicability, potentially ambiguous concepts <em class="rfc2119">must</em> be defined objectively. Definitions can be put in the rule [glossary](#glossary), or they can be defined in the section where they are used.
Subjective properties on the other hand, are concepts like decorative, navigation mechanism and pre-recorded. When possible, subjectivity <em class="rfc2119">should</em> be avoided since it can easily be misunderstood. For example, concepts like headings and images could refer to the tag name, the semantic role, or the element’s purpose on the web page because they are ambiguous. The latter of which is almost impossible to define objectively. In some cases, where meeting the objectivity requirement is impossible, the use of a subjective description in the applicability is acceptable.

Any applicability including subjective descriptions <em class="rfc2119">must</em> use one of the **Allowed Subjective Forms** shown below and place all subjectivity within a glossary definition. Glossary definitions used to identify subjective test targets <em class="rfc2119">must</em> provide a list of features or characteristics that are common to the intended test targets and the logic for determining if an element is applicable.
Copy link
Collaborator Author

@tbostic32 tbostic32 Dec 6, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have had this in my own comments for awhile, but am finally putting it here. From our discussion at TPAC, we settled on basically having two types of definitions. The would include logical definitions (i.e., allowed to use AND, OR, NOT) and the "Getting warmer/colder" approach that generally defines the applicable test targets.

For a rule with an applicability of "The rule applies to any HTML element that is styled as a heading." we would need to create the definition for "Styled as a heading".

Example "getting warmer" definition:
Styled as a heading definition - The more of the following conditions that an element matches, the more likely it is to be a heading.

  • Element text is visually distinct from nearby text, such as through the use of a larger font-size or bolding.
  • Element is clearly delineated from surrounding text, either through the use of spacing or other visual effects.
  • The element text broadly describes the content that follows it in the reading order of the page.

NOTE: The last element in this list may need to be removed, its description mentions nothing about styling and may be the definitive definition of what it means for something to be a heading.

Some of my current thoughts as of 12/5/2023 -

  • The allowed subjective forms do not seem to have gained much traction, they also may just complicate the rules format.
  • We have identified several best practices for creating subjective definitions - creating multiples types of ways we may formulate the definitions and potentially also a method for creating rules for definitions to ensure more global consistency (see Turn "visible" examples into a rule act-rules/act-rules.github.io#2087)
  • Are the glossary definitions really a good way to quality check that an applicability is acceptable? If the definition is only used in one rule it doesn't give us much and the rule is still going to be reviewed anyways.

So what - It seems that we continue to identify best practices for writing subjective rules, but not changes that need to be made to the rules format in order to allow subjective rules. Given this we could simply include only the changes above that allow subjective rules and then have community rule writing guidelines that ensure the quality of the rules. This would make the rules format less prescriptive but much more adaptable. Lastly, I still think it would be beneficial to clearly label rules as objective or subjective (perhaps for both Applicability and Expectation) to ensure the expectations of readers/implementers are clear.


**Allowed Subjective Forms**:
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A couple of thoughts here, is it clear that the things in brackets are the "fill in the blank" portion of the form? I should maybe add more verbiage to this.

Is "Objective target description" the best verbiage we can use to state what the subjectivity is applying to?

Is "role/common design pattern/subjective attribute" good wording for what kinds of subjectivity go with each form? I think not, this to me is the weakest part of this addition and the one that needs the most fleshing out and thought.

1. [Objective target description] is styled as a [role]
2. [Objective target description] functions like a [role/common design pattern]
3. [Objective target description] is/has/expresses [subjective attribute]
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one feels too vague to me. One thing I think I'd like to do is for us to go over the subjective definitions we have today and see if we can categorise them somehow. Maybe see which ones we think would be okay for use in an applicability and which ones aren't.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It will be good to revisit it now with more context, but my initial stab at finding some of the subjectivity types we use are in act-rules/act-rules.github.io#2061 (comment). That is where these 3 forms originally came from, they seemed to deal with the examples I found as well as some I had seen people want to use.


<aside class=example>
<header>Example applicability of an atomic rule testing [WCAG 2.2 success criterion 1.4.2 Audio Control](https://www.w3.org/WAI/WCAG22/quickref/#audio-control):</header>
Expand All @@ -436,6 +443,20 @@ Even concepts like headings and images can be misunderstood. These terms could r
</blockquote>
</aside>

<aside class=example>
<header>Example applicability of a rule with visual headings as a test target</header>
<blockquote>
<p>The rule applies to any HTML element that is styled as a heading.</p>
<p>Since this applicability is subjective, it requires a glossary definition for "styled as a heading".</p>
<p>Styled as a heading defintion - An element is considered to be styled as a heading when it exhibits at least 2 of the following characteristics.</p>
<ul>
<li>Element text is visually distinct from nearby text, such as through the use of a larger font-size or bolding.</li>
<li>Element is clearly delineated from surrounding text, either through the use of spacing or other visual effects.</li>
<li>The element text broadly describes the content that follows it in the reading order of the page.</li>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To avoid including unintended targets, how about making the third item and instead of or? So, (1 OR 2) AND 3.

</ul>
</blockquote>
</aside>
Copy link
Collaborator Author

@tbostic32 tbostic32 Aug 23, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tried to create an example of what form these types of definitions might take. In the format above, I left it up to the definition author to determine the logic behind the classification (i.e., it doesn't always have to be meet 3 of X criteria to apply). For example, I considered making the logic here that a heading should be at least one of the first 2 bullet points and then must meet the 3rd.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I haven't made any changes to the format yet, but here are some of my initial responses to the questions we raised at the last meeting:

What if we have a test target that doesn't meet the definition, but that we would still like to have as a test target? The example given was a heading that only fulfills one or none of the conditions above?

I think in all cases this would mean that the definition requires further expansion/editing. We already have processes in place to handle this, and I think as long as we stick to them we will be fine. I am a bit concerned that we will open the door to "cascading" complexity if we try to make our definitions cover too much ground, but I don't have any methods for preventing that at the moment.

What if we want to specify what something isn't?

With our current conversation, we have discussed (and I believe at least initially agreed) to allow more complex logic inside of the definitions. In my opinion, this means usages of the standard and, or, and not operators will all be allowed when writing these definitions.


### Applicability for Composite Rules ### {#applicability-composite}

The applicability of a composite rule is defined as the union of all applicability definitions from the rules listed in the [input rules](#input-rules). Rule authors <em class="rfc2119">may</em> omit a description of the applicability for composite rules. This can be useful if it is difficult to express the combined applicability in plain language. If the composite rule includes applicability, it <em class="rfc2119">must</em> be the union of all the applicability in the [input rules](#input-rules).
Expand Down