Improve readability of RFC 2119 keywords (MUST, SHOULD…) about community-group HOT 8 CLOSED

👍🏻 I tested VoiceOver and macOS's speech feature, which successfully read the sentences as expected. Not sure about other screen readers.

As a safety check, I looked at the WAI ARIA spec (assuming they're concerned about the accessibility of their technical reports), and they use <em class="rfc2119">KEYWORD</em>, with these styles:

.rfc2119 {
    font-weight: bold;
    text-transform: uppercase;
}

I also gave a go at using small caps in our specs: #68

In case folks want to see what that looks like: https://deploy-preview-68--dtcg-tr.netlify.app/format/#conformance

from community-group.

I agree we should review rendered formating of RFC2119 keywords to improve readability, but using strong seems to be the wrong answer to this issue, both due to incorrect semantics and because it doesn't carry intent well when copy/pasted and quoted. More on that in this article: https://tess.oconnor.cx/2007/08/revisiting-rfc2119-markup

Note that ReSpec renders these keywords in em elements, with an rfc2119 class, so we can style them.

There's been debates in the past about this in the W3C repos, and there was no clear resolution w3c/tr-design#126. Spec editors are free to ignore this particular RFC.

The way I now see it, we have two choices:

1. Adhere strictly to RFC2119 and the W3C manual of style, using UPPER CASE in markdown and rendering them in small caps in HTML, as a readable compromise.
2. Ignore RFC2119, go lowercase both in markdown and rendered HTML: we state that the spec is authored using the RFC keywords without uppercasing them.

Some people really like having uppercase or small caps because it breaks the flow of the sentence to very clearly show critical intent, while other prefer the prose to flow more naturally.

The W3C has gone back and forth between various styles, and all specs differ on this.

My take:

The second solution (lowercase all the things) seems appropriate for experienced spec writers, but could be a little error-prone for us (possible confusion between "normal must/should" and "2119 must/should").

The first solution (strictly adhering to RFC2119 and W3C manual of style, but style them in small caps) could be safer, as it guides spec writers to practice deliberate usage of 2119 keywords.

With all this context now presented, I'd like editors to make this decision, as they're the ones writing the spec.

from community-group.

Agreed.

When we do this, we should also update the wording in the "Conformance" section to reflect that, as it currently reads:

The key words MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

from community-group.

yeah at the time I suggested strong, I thought it was us using all caps for emphasis. It looks more like it's using it as an "instance" of a word to denote how we use it. Not sure if dfn might be more appropriate and then styled to be all caps?

The purpose of my feedback — I'm just thinking about whether screenreaders will read it as a word or think it's an abbreviation and read out the letters. I've heard Mac's "Speech" feature spell out words that weren't meant to be.

from community-group.

In light of @kaelig's tests, my vote would be to go for the 1st choice - i.e. all caps, but wrapped in <em class="rfc2119">.

This is because, if I've understood correctly:

• It follows the W3C's style guide
• VoiceOver will announce them as words (i.e. "must") and spell them out (i.e. "M. U. S. T."), which is what we want.
  • It would be good to know if the same is true for other screen readers, but given that the ARIA spec uses this approach, I'm hoping there's a good chance they do 🤞
• These keywords are important for implementors following the spec, so making them visually distinctive feels like a good idea

from community-group.

Okay. I'm sold. :)

from community-group.

Closed by #68 — happy to revisit if anybody else feels strongly about it.

from community-group.

Agree with option 1. I thought this was already standard style at W3C, as a result of issue #168 discussion in 2018, but maybe I wasn't following closely enough.

from community-group.