Subject: [Rats] document conventions around Capitalization of Terminology

From: Michael Richardson <[email-masked]>
Date: Tue, 13 Apr 2021 11:33:10 -0400

In the RATS Architecture document we have spent some time (maybe too much
time), making sure that if we define some Term, that it is consistently
rendered like a Proper Noun. That is capitalized.
There are some terms which have renderings in both capitalized (our
definition), and uncapitalized (not exactly our definition).

In a document of mine (BRSKI) which has now entered AUTH48, the RPC has
lower-cased all our in-document defined terminology.  I was very surprised by this.
I have asked to have that reversed, and I imagine that my wish will be granted.

But, I am wondering about convention, and I wonder if there is some magic
keyphrase that needs to go into a Terminology Section such to indicate that
to the editors and the readers that we are following that convention.
Or if we should make up such a phrase.

--
Michael Richardson <[email-masked]>   . o O ( IPv6 IøT consulting )
           Sandelman Software Works Inc, Ottawa and Worldwide

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 13 Apr 2021 17:52:35 +0200

On 2021-04-13, at 17:33, Michael Richardson <[email-masked]> wrote:
> 
> if we define some Term, that it is consistently

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

---

From: "Paul Hoffman" <[email-masked]>
Date: Tue, 13 Apr 2021 09:15:27 -0700

> Or if we should make up such a phrase.

The convention for techie writers is to assume that new things should be 
proper nouns. The convention for copy editors is to make them regular 
nouns because over-capitalizing makes documents hard to read.

As a guidepost, in the non-technical world, new nouns that are like the 
new nouns we make are basically never treated as proper nouns.

--Paul Hoffman

---

From: Dave Thaler <[email-masked]>
Date: Tue, 13 Apr 2021 18:16:26 +0000

Paul Hoffman writes:
> The convention for techie writers is to assume that new things should be proper nouns. 
> The convention for copy editors is to make them regular nouns because over-capitalizing makes documents hard to read.

I completely agree with that.

As one of the co-editors of the RATS architecture document that Michael mentioned,
I find it harder to read now that things got capitalized everywhere.

Dave

---

From: Brian E Carpenter <[email-masked]>
Date: Wed, 14 Apr 2021 10:19:38 +1200

> I find it harder to read now that things got capitalized everywhere.

Oh dear. I hate to introduce a potential Red Herring, but an inverse version
of the problem also exists. One of the documents in Cluster 325 (which has
this capitalization problem) happens to contain a couple of sections whose
topic is a lower case parameter name, such as 'asa_handle'. After some
backwards and forwards, the RFC editor has settled on section headings
like '2.3.2.7. asa_handle'. This looks a bit odd, but '2.3.2.7. Asa_handle'
seemed misleading.

   Brian

---

From: tom petch <[email-masked]>
Date: Wed, 14 Apr 2021 12:44:11 +0100

> lower-cased all our in-document defined terminology.  I was very surprised by this.

If this happened to me, I would be more than suprised, I would be 
furious and wondering how to take my revenge:-)

I looked at the Style Guide and page 6 has a section on Capitalization 
[sic] but it only covers titles, section headings and the like, nothing 
about using capitalisation in text to indicate a technical term, which 
for me is an essential part of making our output easier to understand.

Tom Petch

> _______________________________________________
> rfc-interest mailing list
> [email-masked]
> https://www.rfc-editor.org/mailman/listinfo/rfc-interest
>

---

From: Henning Schulzrinne <[email-masked]>
Date: Wed, 14 Apr 2021 10:18:30 -0400

Capitalization of terms that are not proper names is often considered a bad
idea and bad style - this is English, not German, after all. Most standard
style guides in science and technology writing frown on this.

---

From: Sandy Ginoza <[email-masked]>
Date: Thu, 15 Apr 2021 23:31:07 -0700

Hi Michael,

> Or if we should make up such a phrase.

We recommend the following on <https://www.rfc-editor.org/styleguide/tips/ <https://www.rfc-editor.org/styleguide/tips/>>:

Keeping a list of directives to provide to the RFC Editor once your document is approved for publication — for instance, if specific terms must appear in a certain way (spelling, hyphenation, capitalization, etc.), send us mail with your draft string in the subject line.

Please either send mail describing your style choices or include a note in the text itself (e.g., For the RFC Editor: …).  Mail should be sent to [email-masked].

In general, we agree with the comment that over-capitalization often detracts from readability.  However, when terms are (seemingly) inconsistently capitalized, we review how the terms are used and strive for consistency within the document, cluster, and other referenced documents.  

Thanks for raising this topic for discussion - we hope to receive more style notes from authors.  
 
Sandy Ginoza
for the RFC Production Center 

> On Apr 13, 2021, at 8:33 AM, Michael Richardson <[email-masked]> wrote:
> 
>

---

From: Henk Birkholz <[email-masked]>
Date: Fri, 16 Apr 2021 08:48:54 +0200

Hi Sandy,

thank you for the comprehensive and clear reply. We'll adhere to your 
highlighted recommendation.

Viele Grüße,

Henk (as an author & editor)

On 16.04.21 08:31, Sandy Ginoza wrote:
> We recommend the following on <https://www.rfc-editor.org/styleguide/tips/>:
> 
>     Keeping a list of directives to provide to the RFC Editor once your
>     document is approved for publication — for instance, if specific
>     terms must appear in a certain way (spelling, hyphenation,
>     capitalization, etc.), send us mail with your draft string in the
>     subject line.
> 
> 
> Please either send mail describing your style choices or include a note 
> in the text itself (e.g., For the RFC Editor: …).  Mail should be sent 
> to [email-masked] <mailto:[email-masked]>.
> 
> 
> 
> In general, we agree with the comment that over-capitalization often 
> detracts from readability.  However, when terms are (seemingly) 
> inconsistently capitalized, we review how the terms are used and strive 
> for consistency within the document, cluster, and other referenced 
> documents.
> 
>> On Apr 13, 2021, at 8:33 AM, Michael Richardson <[email-masked] 
>> <mailto:[email-masked]>> wrote:
>>
>>
>> Michael Richardson <[email-masked] 
>> <mailto:[email-masked]>>   . o O ( IPv6 IøT consulting )
>> [email-masked] <mailto:[email-masked]>
> RATS mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/rats
>