Re: [Rats] [rfc-i] document conventions around Capitalization of Terminology

[Carsten Bormann <[e-mail]>]

On 2021-04-13, at 17:33, Michael Richardson <[e-mail]> wrote:
> 
> if we define some Term, that it is consistently
> rendered like a Proper Noun. That is capitalized.

We had endless amounts of fun with that in RFC 7252.
E.g., there are the terms “Confirmable” and “Non-confirmable” [sic!] that are far enough from their English meanings that we insisted on having them capitalized.

We didn’t do that for other terms such as “endpoint”, which are of course used with a different meaning even in OAuth.  I tend to think that was a mistake, because a capitalized form would have alerted readers to look for the definition instead of assuming the usual misuse of the term.

But then, the document tends to read a bit on the clumsy side.

Having said that, nothing can be saved in paragraphs like this: :-)

   A recipient might receive the same Non-confirmable message (as
   indicated by the Message ID and source endpoint) multiple times
   within NON_LIFETIME (Section 4.8.2).  As a general rule that MAY be
   relaxed based on the specific semantics of a message, the recipient
   SHOULD silently ignore any duplicated Non-confirmable message and
   SHOULD process any request or response in the message only once.

With 3 BCP14 keywords, a protocol parameter, the capitalized words Section, Non-confirmable and Message ID, capitalizing Endpoint would not have ruined the day.
(But keeping request, response and message lower case does preserve some minimal sanity.)

So my verdict would be: The authors of non-trivial documents should think about capitalization and actually reveal their approach in the Terminology section, so not only the RFC editor but any reader can benefit from that knowledge.

Grüße, Carsten