People are too willing to slap on allow-2119

[domenic]

Currently if you use a disallowed RFC 2119 keyword in a non-normative section, you get this error:

RFC2119 keyword in non-normative section (use: might, can, has to, or override with <span class=allow-2119>):

I've seen a lot of people just go straight for that last option, not seeming to understand that this rule is there for a good reason, and that exceptions are meant to be very rare.

My best suggestion is that "we" (me, probably?) puts together some documentation about this somewhere, and then we expand the error message to link to it. And maybe even we remove the quick-fix from the error message? So it becomes something like:

RFC2119 normative keyword in non-normative section. Use a synonym, or learn more at https://speced.github.io/bikeshed/#accidental-2119, including workarounds for exceptional cases.

And here's a draft of what that documentation could look like:

A key aid to specification clarity is the distinction between normative requirements and informative notes, examples, and explanations. An important way to signal normative requirements is using the RFC 2119 keywords, "must", "must not", "required", "shall", "shall not", "should", "should not", "recommended", "not recommended", "may", and "optional". See more discussion of these keywords and their usage in Infra.

Using these keywords in a context marked explicitly as non-normative is confusing spec-writing. The reader becomes unsure whether you are intending to communicate a normative requirement, hidden inside a non-normative section, or whether you are having a non-normative discussion with false precision.

This issue is usually best resolved by using synonyms that have not been given the same magical normative status: e.g., "can" or "might" instead of "may"; "has to" or "will" instead of "must"; "will likely" instead of "should", etc.

In rare cases, this check misfires. For example, when talking about the month of May in an example, or when talking about the optional Web IDL keyword in notes, or when giving a warning about how an older spec required something but modern specs intentionally contradict it. For such rare cases, you can override this check by adding <span class=allow-2119> around the offending keyword, or an ancestor element of it.

---

Thoughts or refinements? I can try to work on a PR implementing the above if you agree.

[inexorabletash]

I've seen a lot of people just go straight for that last option

Are you seeing this in published specs in the wild, or is it something you tend to catch during review?

Either way: SGTM. And I appreciate the "using synonyms" guidance in the proposed documentation.

[domenic]

Are you seeing this in published specs in the wild, or is it something you tend to catch during review?

It's something I tend to catch during review, but it looks like a few have slipped through:

• https://github.com/search?q=org%3Aw3c%20allow-2119&type=code
• https://github.com/search?q=org%3Awicg%20allow-2119&type=code

[tabatkins]

This looks good to me, I'm happy to have the workaround be pushed further into the docs rather than presented in the error message. PR welcome!