How to Read an RFC (2018)

I just recently heavily refactored a lib [1] and looked a lot at two RFCs from 2013.

I don’t know how representative they are, but overall I got the impression that it’s a lot better than casual specs and academic papers, and good language. Another huge plus is that they don’t change every week, and are published publicly.

But at the same time, these ones were unnecessarily complex and with too few examples/pseudo-code, which leaves quite a bit of room ambiguity and implementation divergence.

I used to think RFCs were impenetrable and superhuman, but now I see it as a bit more mortal. If anything, I think simplicity is the best cure for interop issues – and that includes reducing the amount of knobs. Writing a spec in natural language is certainly a good exercise that can feed back into – and help simplify – the implementation as well.

[1]: https://github.com/betamos/zeroconf

I had to read the OAuth 2.0 RFC (and OIDC specs) while implementing an auth service and found it to be pleasantly painless. By the end, I think I consumed the vast majority of the document itself, but during the planning and implementation phases of my task it was _mostly_ a matter of reading a few relevant chunks at a time (as opposed to reading the whole thing "cover to cover"). It was pretty intuitive to just look for relevant sections.

There's several times where I've started jumping to RFC's in my work as a sysadmin recently.

Typically in the context of "what does this DNS record _actually_ do", or "OK, I need to know this random detail about an email header a client asked about", or other small fiddly bits of knowledge.

With practice, it's gotten surprisingly easy to just skim or ctrl-f for the relevant section. Definitely a skill worth learning - it's much easier when on the phone with a client to google "$protocol RFC -> https://www.rfc-editor.org/rfc/rfc#### -> ctrl-f $topic" then it is to be stuck reading top ten list style blogspam about why $Thing is important, and you should just pay us.

The people I have worked with would not read RFCs frequently, while many were not aware of their existence despite working with technologies for which they were authoritative. Thanks for submitting the guide, it's a great starting point to forward someone. Coincidentally, the first one I've read was also the OAuth 2.0 one (used to print them out and read over the holidays!).

Which brings me to the mention in the body of the article of a new RFC format with SVG graphics, which is advertised as an improvement over an unreadable plaintext format. Call me old-fashioned, but I've always found the plaintext version the most palatable reading: strict in its uniformity, entirely self-contained and yes, printable. Hope none of that is compromised in the future!

Since Naur is on the front page again [0] it may be worth mentioning that one would do well to know how to read grammars and the ABNF [1] that shows up time and time again throughout RFCs.

[0] https://news.ycombinator.com/item?id=37263121

[1] https://www.rfc-editor.org/rfc/rfc5234