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

Carsten Bormann <cabo@tzi.org> Tue, 13 April 2021 15:52 UTC

Return-Path: <cabo@tzi.org>
X-Original-To: rats@ietfa.amsl.com
Delivered-To: rats@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 830E73A1C5C for <rats@ietfa.amsl.com>; Tue, 13 Apr 2021 08:52:42 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.918
X-Spam-Level:
X-Spam-Status: No, score=-1.918 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RCVD_IN_DNSWL_BLOCKED=0.001, RCVD_IN_MSPIKE_H4=-0.01, RCVD_IN_MSPIKE_WL=-0.01, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id ACROhDyDVHp7 for <rats@ietfa.amsl.com>; Tue, 13 Apr 2021 08:52:38 -0700 (PDT)
Received: from gabriel-vm-2.zfn.uni-bremen.de (gabriel-vm-2.zfn.uni-bremen.de [134.102.50.17]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 0590C3A1C57 for <rats@ietf.org>; Tue, 13 Apr 2021 08:52:37 -0700 (PDT)
Received: from [192.168.217.118] (p548dc178.dip0.t-ipconnect.de [84.141.193.120]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by gabriel-vm-2.zfn.uni-bremen.de (Postfix) with ESMTPSA id 4FKVVX12L4z1049; Tue, 13 Apr 2021 17:52:36 +0200 (CEST)
Content-Type: text/plain; charset=utf-8
Mime-Version: 1.0 (Mac OS X Mail 13.4 \(3608.120.23.2.4\))
From: Carsten Bormann <cabo@tzi.org>
In-Reply-To: <10996.1618327990@localhost>
Date: Tue, 13 Apr 2021 17:52:35 +0200
Cc: rats@ietf.org, rfc-interest <rfc-interest@rfc-editor.org>
X-Mao-Original-Outgoing-Id: 640021955.5819761-7ccd668df243e7111f83a8e984d263f3
Content-Transfer-Encoding: quoted-printable
Message-Id: <7F41392A-73D9-4D3B-8CEB-179ED173149A@tzi.org>
References: <10996.1618327990@localhost>
To: Michael Richardson <mcr+ietf@sandelman.ca>
X-Mailer: Apple Mail (2.3608.120.23.2.4)
Archived-At: <https://mailarchive.ietf.org/arch/msg/rats/vE_-pyyHq5dx6cZwNqnxq-EBeQ8>
Subject: Re: [Rats] [rfc-i] document conventions around Capitalization of Terminology
X-BeenThere: rats@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Remote ATtestation procedureS <rats.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/rats>, <mailto:rats-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/rats/>
List-Post: <mailto:rats@ietf.org>
List-Help: <mailto:rats-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/rats>, <mailto:rats-request@ietf.org?subject=subscribe>
X-List-Received-Date: Tue, 13 Apr 2021 15:52:43 -0000

On 2021-04-13, at 17:33, Michael Richardson <mcr+ietf@sandelman.ca> 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