Inconsistent language or unclear distinction in "Document conformance requirements..."

[rschristian]

Scrolling through the list of elements, the language is either inconsistent or suggests a distinction that is not made clear in the document, for example:

• bdo: Any role, though "generic" SHOULD NOT be used.
• blockquote: Any role, though "blockquote" is NOT RECOMMENDED.

https://www.w3.org/TR/html-aria/#docconformance

From my understanding, this is a language consistency issue and this isn't actually pointing out a distinction. If that's correct, I'd be happy to go through and switch all these "SHOULD NOT"s to "NOT RECOMMENDED" (as the note above makes it clear using the implicit role does serve a purpose in some cases, hence, "not recommended" seems like better language to use).

[pkra]

Just to clarify: "SHOULD NOT" and "NOT RECOMMENDED" are interchangeable as per rfc2119, see also https://www.w3.org/TR/html-aria/#conformance.

(That's not saying that the editors might like more consistency in their spec.)

[rschristian]

Great, thank you so much for that! I was not aware.

In that case, I'll try to run through and get a PR together that alters the language to be a bit more consistent, happy to invest a little bit of my time in the chance others think it's an improvement too.

Ended up running into the following example only after filing this issue, which I think shows off the issue a bit more:

Roles: group, none or presentation. (If not a descendant of an article, aside, main, nav or section element, or an element with role=article, complementary, main, navigation or region, then role=banner is also allowed, but NOT RECOMMENDED. Otherwise, role=generic is also allowed, but SHOULD NOT be used.)

Subsequent sentences using different language would, to me anyhow, indicate a difference.

[scottaohara]

the terms are interchangeable per rfc2119, but we purposefully use "SHOULD NOT" for generic since the ARIA spec indicates that authors SHOULD NOT use that role.

we use NOT RECOMMENDED as a tonally 'lighter' version of SHOULD NOT for instances like <blockquote role=blockquote> since it's just silly for a dev to do that, but in most cases there's nothing bad that will happen there.

there are two inconsistencies here, that i can see, where we say "SHOULD NOT" for the redundant use of a group role. that needs fixing to "NOT RECOMMENDED"

[rschristian]

we use NOT RECOMMENDED as a tonally 'lighter' version of SHOULD NOT for instances like <blockquote role=blockquote> since it's just silly for a dev to do that, but in most cases there's nothing bad that will happen there.

Hm, see that starts to sound like they aren't in fact interchangeable, if one is a "do not do this" and the other is "it's silly but not problematic", so I'm back to being confused.

I'm working on some TS types for a JS framework to (hopefully) guide users in the simple cases but this doc leaves me quite confused as to the actual intentions behind the language. Frankly, I can't say I can walk away from this as-is with a better understanding of what's disallowed and what is recommended against for the simple case of being redundant.

Better choices in language would be much appreciated.

[scottaohara]

i'll rephrase...

they're both things authors should not do. neither are 'invalid' per use of ARIA, but they can be redundant/meaningless in these instances, and why they are called out as not good ideas in this spec.

with role=generic there is no good reason to use it on an element that is already a generic by default. ARIA tells authors not to use this role. we use SHOULD NOT there as it's more understood as a warning to developers than 'not recommended' - see this thread as a reference point to that.

with role='element's-implicit-role' there is generally no good reason to do this, but SOMETIMES a corner case might come up (e.g., to force a list without list marker styling to be a list in webkit). We use not recommended here since while often not necessary, we don't want to completely turn people off - which 'should not' has had the effect of doing in the past.

we are not going to use MAY here, as that is inaccurate and removes any sense of a warning.

[rschristian]

Gotcha, thanks! I definitely misunderstood the intention in that case.

I suppose I won't try to fix this then as I'm still not 100% on things but my 2¢ is the "tonally lighter" use makes this far less clear. Not necessary advocating for "MAY", but using very different verbiage (not recommend & should not) which is actually meant to be synonymous(? Weird choice, but I get probably not yours to make) and using them to relate different ideas doesn't make for a super clear doc.

Sorry, I don't have any answers at the moment and I am legitimately trying to be productive here, but I spent a fair few hours pouring over this doc tonight to realize I apparently misunderstood significant chunks of it. I have to imagine there's some way to not necessarily reformat but present it differently to cover those ideas a bit better. Or, of course, always free to call it user error & move on, I certainly wouldn't be offended. I don't read these docs often anyhow, maybe this is just par for the course.

[scottaohara]

i'm going to leave this issue open so that it can be noodled on a bit. i understand your point. i'm just not sure how to change this without either undoing the normative text, or backtracking on the purposeful distinction that was made due to the prior feedback that resulted in these variations.