Difference between revisions of "RFC Readability"
|Line 87:||Line 87:|
author who imposed that in RFC 5766):
author who imposed that in RFC 5766):
* An implementer does not need to read the informative parts
* An implementer does not need to read the informative parts (abstract, introduction, overview of operations, informative references, appendixes) to implement the RFC.
(abstract, introduction, overview of operations, informative
references, appendixes) to implement the RFC.
* The text should not rely on examples to explain the protocol
* The text should not rely on examples to explain the protocol (message state charts, which are examples, are often used for that purpose). In fact an RFC should still be implementable after removing all the examples.
(message state charts, which are examples, are often used for that
purpose). In fact an RFC should still be implementable after removing
all the examples.
* It should be short, and to the point. Most RFCs are far too verbose
* It should be short, and to the point. Most RFCs are far too verbose and it is at the cost of spending time extracting the good stuff from it.
and it is at the cost of spending time extracting the good stuff from
=== Other comments ===
=== Other comments ===
Revision as of 18:52, 12 February 2021
Warning: This is an early brainstorming page
Characteristics of readable RFCs
- Very short with good examples
- Introductory, Architecture, or Roadmap documents for complex topics
- Start with an high-level overview and then go through the protocol step-by-step focusing on the specification to be short and to the point (while leaving reasoning and additional explanations for later)
- Avoid too many external or normative references
Example RFCs and why they're good
Wes: IMAP: RFC 3501
- RFC 3501 has solid examples throughout the document
Suggestions by Others
- [RFC 6120] - XMPP
- [RFC 6648] - Deprecating the X- prefix
- [RFC 7525] - Recommendations for secure use of TLS
Others he likes:
- [RFC 3365] - Strong Security Requirements for Internet Engineering Task Force Standard Protocols
- [RFC 3552] - Guidelines for Writing RFC Text on Security Considerations
- [RFC 4122] - A Universally Unique IDentifier (UUID) URN Namespace
- [RFC 4648] - The Base16, Base32, and Base64 Data Encodings
Aqua Q Glass
- [RFC 2317] -- classes addressing -- "It reads well and easily thorough, and plain, as in text."
- Wes notes: short, good examples, operational considerations
Andrew G. Malis
RFC 826 - ARP because "If "interoperable implementations" is an indicator, then it's hard to beat RFC 826, which must have many many thousands, if not millions, of independent implementations by now."
[RFC 4101] - Writing protocol models, "includes many sub-examples"
[RFC 7754] Technical Considerations for Internet Service Blocking and Filtering, because it is a "masterpiece with regards to readability"
[RFC 7230] (and friends) Hypertext Transfer Protocol (HTTP/1.1). "Very readable and understandable".
Also thinks FTP and SMTP are likely good from memory.
[RFC 793] - TCP -- 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.
[RFC 6325] - Routing Bridges (RBridges): Base Protocol Specification
Although I am one of the authors, I think RFC 6325 is pretty clear. When it went through the IESG a few ADs commented that it was easy to understand, for a document of its size.
[RFC 6503] - Centralized Conferencing Manipulation Protocol
"it's special because this protocol was the basis for the original Meetecho implementation."
My job is to implement RFCs and so my definition of a "good" RFC is restricted to how easy it is to write a correct and interoperable implementation. On the ones I implemented RFC 5766 has most of the properties I now expect for a "good" RFC (Philip Matthews is the author who imposed that in RFC 5766):
- An implementer does not need to read the informative parts (abstract, introduction, overview of operations, informative references, appendixes) to implement the RFC.
- The text should not rely on examples to explain the protocol (message state charts, which are examples, are often used for that purpose). In fact an RFC should still be implementable after removing all the examples.
- It should be short, and to the point. Most RFCs are far too verbose and it is at the cost of spending time extracting the good stuff from it.
- The normative structure should more or less follow a logical sequence that makes sense for an implementer. RFC 5766 takes the implementer step by step: on the client side creating an allocation, then sending it; on the server side receiving it and sending a response; back on the sending side, receiving the response and process it. Some RFCs just mix all these things together, and the implementer has to prepare the work by disentangling that mess, which is no fun at all.
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.
Things that don't work
- Biting off more that you can chew
- the flip side: a gazillion tiny documents are hard to read
- Forward references
Some thoughts about things to include here (RW)
- Not everything needs to be in the same document. It's probably good to describe what you are trying to achieve in a separate document, or at least in a separate section of the document, rather than trying to blend these things into the document specification.
- Use cases should be provided as a way to "flesh out" the description of what you are trying to achieve; uses cases should not be a substitute for describing what you are trying to achieve. If there is a single use case that cannot be generalized, the protocol or extensions might not be well thought out or extensible.
- Try to describe the problem you are solving first, then describe the solution. the "problem" is not a use case, but rather what the protocol is trying to accomplish, such as carrying data from host to host, etc.
- Describe what each part of the protocol intends to do, or what problem it is trying to solve. If you work from the RINA model, what part of the protocol solves each of the four problems: marshaling, multiplexing, managing errors, and managing flow control. If the protocol does not solve all four, then what other protocols are you relying on to solve those problems? If you are dealing with a control plane, then information needs to be distributed, loop free paths need to be calculated, etc. Break things down into the problems to be solved, then describe how they are solved.
- Again -- perhaps not in the same document, but perhaps in an appendix, try to describe some of the tradeoffs involved in the protocol design as it is described. This will help readers understand why things are the way they are, providing context that aids in understanding.