Difference between revisions of "RFC Readability"

From IAB Wiki
Jump to navigation Jump to search
Line 30: Line 30:
* [RFC4122]
* [RFC4122]
* [RFC4648]
* [RFC4648]
==== Aqua Q Glass ====
* [RFC2317] -- classes addressing -- "It reads well and easily thorough, and plain, as in text."
** Wes notes: short, good examples, operational considerations


== Things that don't work ==
== Things that don't work ==

Revision as of 00:31, 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

IMAP: RFC3501

  • Solid examples throughout the document

Suggestions by Others

Peter Saint-Andre

Authored:

  • [RFC6120]
  • [RFC6648]
  • [RFC7525]

Others he likes:

  • [RFC3365]
  • [RFC3552]
  • [RFC4122]
  • [RFC4648]

Aqua Q Glass

  • [RFC2317] -- classes addressing -- "It reads well and easily thorough, and plain, as in text."
    • Wes notes: short, good examples, operational considerations

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.