Reconsider how many notes we have in rules

[WilcoFiers]

There are a lot of notes in rules, some rules have 4 or 5 rules for two lines of applicability and expectation. We should rethink how frequent we resort to using notes, and if there are better solutions.

[EmmaJP]

Are there some specific examples you could reference, please? There are a lot of rules now.

[Jym77]

@EmmaJP check the recent PRs about removing some notes.
#1340, #1341, #1342, #1343, #1344.

[Jym77]

As mentioned during the CG call, one point that becomes more visible with this policy is the difference between two kinds of assumptions:

• assumptions where, if it doesn't hold the rule may fail while the SC pass (e.g. "language is programatically set by lang attribute" => if language is set by HTTP headers, the rule will fail but the SC will pass). These are super important as the fail-on-fail relationship is at the core of the format and we must be cristal clear on the reasons why it may not hold.
• assumptions where, if it doesn't hold the rule may pass while the SC fails (e.g. "there can be more than one title element and it can be outside head" => if it's not true and WCAG actually means that 2 titles is bad, then the rule will pass on pages with 2 titles where the SC fails). This are OK-ish as almost all our rules have a "passing: further testing needed". It is good to document the possible gaps, but this does not create false positives which we absolutely want to avoid.

Moving some notes to assumptions (eg https://github.com/act-rules/act-rules.github.io/pull/1340/files#diff-0778ae27333525135efc58a1e903eadeR52) creates a lot of the second case assumptions (as these tend to be in notes previously).

I'd like us to make sure whenever we write an assumption whether it is a first or second case assumption. We're usually pretty good at that by adding sentences like "if this is not the case, the rule may fail while the SC pass" or (as in https://github.com/act-rules/act-rules.github.io/pull/1340/files#diff-0778ae27333525135efc58a1e903eadeR52) "if this is not the case, failing the rule still means the SC fails".
Let's keep writing these explicit "what happens if false" conclusion to assumptions 😄

[Jym77]

Another way to remove (some) notes is to move the content to the "Background" section.

So far, we've mostly used it for list of references but, according to the ACT format (emphasis mine):

An ACT Rule may contain information about the background for the development of the rule, or references to relevant reading.

So, I feel that many "explanatory only" notes can move to the Background section. This is a place for non-normative text and for explaining some of the reasoning.

Typically (example I'm working on), role attribute has valid value has the following notes in Applicability:

Note: The role attribute is a set of space separated tokens. Having it contain at least one non-ASCII whitespace character ensures that there is at least one token in that set.

Note: Having a whitespace separated list of more than one token in the value of the role attribute is used for what is known as fallback roles. If the first token is not accessibility supported (or valid), the next one will be used for determining the semantic role of the element, and so forth.

None of these are strictly needed. I do like the first one as it explains a somewhat contrived Applicability. I think they both go well in the "Background" section as it is extra information about why the rule is written this way and not another.

[WilcoFiers]

Taking it off the agenda. We need to update the design doc to explain how to deal with notes. Assigned it to myself for now.