Subject: [rfc-i] I need your "good" RFCs

From: Wes Hardaker <[email-masked]>
Date: Thu, 11 Feb 2021 13:50:10 -0800

Good folks,

I'm looking for people's favorite RFCs with respect to readability and
understand-ability.  Do you have ones that have always impressed you as
your favorites as how RFCs should be written to make their protocol/etc
easily understood?  If so, send a note my way (ideally using this
subject line).  I don't necessarily think you need to do a reply-all.

[And yes, I recognize that this is a subjective ask, and everyone will
have a different opinion as to "what is readable" and "what is
understandable".  That's ok -- I'm asking for opinions and not facts].

-- 
Wes Hardaker
USC/ISI
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Christian Huitema <[email-masked]>
Date: Thu, 11 Feb 2021 16:22:27 -0800

> understandable".  That's ok -- I'm asking for opinions and not facts].

Wes,

That's a bit what I was trying to do in RFC 8963. Using citation counts 
and web search referrals as a proxy for "RFC that appeal to a wide 
audience". Out of the 60 RFC listed in 3 sets of 20 samples for 1998, 
2008, and 2018, the 4 RFC with more than 100 references were:

RFC 2267 - Network Ingress Filtering: Defeating Denial of Service 
Attacks which employ IP Source Address Spoofing
RFC 8446 - The Transport Layer Security (TLS) Protocol Version 1.3
RFC 5326 - Licklider Transmission Protocol - Specification
RFC 2404 - The Use of HMAC-SHA-1-96 within ESP and AH

Clearly, out of about 9000 RFC, many more would meet the criteria. But 
there has to be something good about these 4.

-- Christian Huitema

---

From: Brian E Carpenter <[email-masked]>
Date: Fri, 12 Feb 2021 17:25:03 +1300

> there has to be something good about these 4.

If you want to take a wider view, perhaps citations as counted by (e.g.)
Google Scholar might be interesting. I'm not sure I have enough Google fu
to do that (except for my own RFCs, which is a biased sample, but
the numbers range from 675 to 0).

But of course citation != approval. The 675 citations are for RFC 3056,
which describes a mechanism deeply hated by many ISPs.

   Brian

---

From: Joseph Touch <[email-masked]>
Date: Thu, 11 Feb 2021 20:36:54 -0800

> On Feb 11, 2021, at 1:50 PM, Wes Hardaker <[email-masked]> wrote:
> 
> 
> Good folks,
> 
> understand-ability.  

RFC793 remains a great model for how to spec a protocol - including defining the internal state machine AND the abstract API.

Especially because it predates the decision* that APIs weren’t part of protocols.

Joe

* regrettably and incorrectly.

---

From: Ted Lemon <[email-masked]>
Date: Fri, 12 Feb 2021 08:50:33 -0500

RFC7230 and friends, and RFC7540/1. Very readable and understandable. ISTR the FTP spec and the SMTP spec were very good as well, but haven’t looked at them in a long time. 

> On Feb 11, 2021, at 16:50, Wes Hardaker <[email-masked]> wrote:
> 
> 
> Good folks,
>

---

From: Wes Hardaker <[email-masked]>
Date: Fri, 12 Feb 2021 09:42:51 -0800

Ted Lemon <[email-masked]> writes:

> RFC7230 and friends, and RFC7540/1. Very readable and
> understandable. ISTR the FTP spec and the SMTP spec were very good as
> well, but haven’t looked at them in a long time.

Thanks.  I have always thought the IMAP spec was very readable too, for
that matter.

---

From: Wes Hardaker <[email-masked]>
Date: Fri, 12 Feb 2021 09:46:18 -0800

> which describes a mechanism deeply hated by many ISPs.

Yeah, I'm looking for ones not necessarily cited (as popular protocols
that are badly written and hard to understand are still frequently
cited).  I do think that citations are highly valuable, and Christian's
work in 8963 is definitely highly helpful.
-- 
Wes Hardaker
USC/ISI
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Michael Richardson <[email-masked]>
Date: Fri, 12 Feb 2021 14:00:26 -0500

> If you want to take a wider view, perhaps citations as counted by
    > (e.g.)  Google Scholar might be interesting. I'm not sure I have enough

Documents with a lots of Updates, (which are citations), may be examples of
poorly written documents that needed a lot of correcting :-)

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

---

From: Christian Huitema <[email-masked]>
Date: Fri, 12 Feb 2021 11:46:15 -0800

> poorly written documents that needed a lot of correcting :-)

Maybe we should not overthink that. Wes was asking for a sample of 
"good" RFCs, letting people respond with whatever their personal choice 
is for "good". So let's do that. Once he has gotten several responses, 
it will be up to him to read the RFCs mentioned in the response and try 
to analyze what made those "good". That's a lot of work, and I am glad 
that he is undertaking it!

-- Christian Huitema

---

From: tom petch <[email-masked]>
Date: Tue, 16 Feb 2021 09:31:53 +0000

> work in 8963 is definitely highly helpful.

I said earlier that TCP and the trio of SNMPv1 RFC were high on my list. 
  I think it worthwhile to say what are not, and top of that list would 
be the original, core specifications of IPv6.  I say this because of the 
thousands and thousands of posts about a range of topics along the lines 
of 'it meaans this', 'no it does not'; rinse and repeat.  Followers of 
the lists will recognise such as
M and O bits
site local
length of prefix and interface ID
header insertion
The text of this last was honed and honed and the meaning is completely 
clear.  That is, it has one meaning to the IPv6 community but Spring did 
not want to conform to that and so found another clear meaning, in what 
has been called the devil's paragraph.

Currently you may find 50 posts a day on the meaning of 'local' and 
'global'.

Quite why this cluster of RFC have been so troublesome I am unclear, but 
they are, as the posts show, and that in turn may well have hindered the 
deployment of IPv6.

Tom Petch

---

From: Joseph Touch <[email-masked]>
Date: Tue, 16 Feb 2021 14:36:25 -0800

> On Feb 16, 2021, at 1:31 AM, tom petch <[email-masked]> wrote:
> 
> I said earlier that TCP and the trio of SNMPv1 RFC were high on my list.  I think it worthwhile to say what are not, and top of that list would be the original, core specifications of IPv6. 

There are many on my list to avoid - starting, first and foremost, those that acceded to the directive of “no API in a protocol spec”.

A protocol spec without an (abstract) API isn’t a protocol spec.

In my courseware (for intro to nets), I define a protocol spec as a finite state machine (FSM) as follows:

	- list of states
	- set of upper layer inputs/outputs (the abstract API)
	- set of messages transmitted/received (the “on the wire” format)
	- set of timers to be set or trigger 
	- a table that maps every input (API input, message receipt, and/or timer trigger) and state combination to a new state and set of outputs (API output, message sent, and/or timer set)

PS - “protocol spec as FSM" isn’t merely a convenience or convention. It’s fundamental, based on what you get when you take a Turing machine and connect it to a communication channel, i.e., a FSM is a Turing machine that can’t “un-send” its outputs.

Joe

---

From: Wes Hardaker <[email-masked]>
Date: Wed, 17 Feb 2021 06:38:38 -0800

Christian Huitema <[email-masked]> writes:

> "good" RFCs, letting people respond with whatever their personal
> choice is for "good". So let's do that. Once he has gotten several
> responses, it will be up to him to read the RFCs mentioned in the
> response and try to analyze what made those "good". That's a lot of
> work, and I am glad that he is undertaking it!

I deliberately left out good, yes.  And I do want to see if there are
some common characteristics across them.

It's been long enough (conversation has slowed) that I can reveal I'm
most interested in "readability" and "understandability".  But I was
curious if the ones people suggested would be good from a technical
point of view (good work) vs readability.  IE, are there RFCs that
people consider "good" but are not well written or easily understood?

But in the end, the discussions both public and comments sent directly
to me have largely talked about readability which has been highly helpful.