RFC Readability

From IAB Wiki
Jump to navigation Jump to search

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

Peter Saint-Andre


  • [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."

Sam Weiler

[RFC 4101] - Writing protocol models, "includes many sub-examples"

Töma Gavrichenkov

[RFC 7754] Technical Considerations for Internet Service Blocking and Filtering, because it is a "masterpiece with regards to readability"

Ted Lemon

[RFC 7230] (and friends) Hypertext Transfer Protocol (HTTP/1.1). "Very readable and understandable".

Also thinks FTP and SMTP are likely good from memory.

Joe Touch

[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.

Donald Eastlake

[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.

Other comments

Christian Huitema

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.