Writing is hard. Writing clearly is harder. Writing clearly in a way that won't run the reader out of the room is harder still. So my hat is off to anyone writing an RFC.
Now there were a couple of fertile points in the article that could bear more development in another piece.
1. An RFC sometimes focuses on the sender, without then turning to the receiver. For example, suppose it says that the Foo header must not contain Bar. So if a sender sends a header of "Foo: Bar" then it is clearly "nonconformant." But what is the recipient to do? Ignore it, send a certain error message, what? This is especially pertinent given that the Robustness Principle advises that you "Be conservative in what you do, be liberal in what you accept from others" (https://en.wikipedia.org/wiki/Robustness_principle).
The takeaway is, I think that the IETF should work it explicitly and prominently into the RFC template. In the editor's guide or whatever for how to write an RFC, it should call out this very problem and say something like, "For every rule you lay down, be sure to address how the recipient should handle it when the sender breaks the rule."
2. RFCs should remember that readers are humans. For example, "In the example above, whitespace isn’t allowed around the semicolon, but you can bet that some people will put it there." Right. Some people will put it there because for 20 years in everyday writing they have seen semicolons followed by whitespace. It is part of being a writer to not just put your claim in "grammatical English" but also to take into consideration the reader's culture and background. You can't say, "Well, there clearly is no whitespace in the Backus–Naur form that I painstakingly laid out for you." Humans are not computers. They are not functions. They do not always return the same output for a certain input. This is because they are always entertaining several streams of input, most of which you don't have control over.
One of the reasons why I prefer insecurity indicators over security indicators is that the user doesn't have to know which parts of the UI are trusted to distinguish secure from insecure sites.
(Another important reason is that an encrypted site is not necessarily secure, so the security indicator can be taken as more of an endorsement of the site than intended)
Personally I think the most important thing about reading RFCs is to do it in the first place. Note that Arch Linux users can install the 'rfc' package to get them in /usr/share/doc/rfc/txt/.
Debian (and derived distros) also has several RFC packages. Principally:
doc-rfc,
doc-rfc-experimental,
doc-rfc-fyi-bcp,
doc-rfc-informational,
doc-rfc-misc,
doc-rfc-old-std,
doc-rfc-others,
doc-rfc-std, and
doc-rfc-std-proposed.
To address the elephant in the room: this is a repost, but it's really useful for newer programmers looking to familiarize themselves with the (still ubiquitous) RFC format, and there are always new programmers browsing HN.
We need more reposts of cool submissions that were overlooked, not fewer!
The mods have even implemented two systems to „rescue“ submissions: invitations to repost with a bonus and auto-repost. And I‘m also working on that, most of my submissions are reposts. :-)
Inspired by this topic I asked the question on how to read documentation [1] (I searched for it, it didn't seem to be there). I really could improve my documentation reading skills but don't know where to effectively search for it (I normally search on HN for quality content on technical topics).
I already know the difference between "MUST", "MUST NOT", "MAY", "SHOULD", "SHOULD NOT", "Obsoletes", et al, but I still feel like there's an RFC code that I haven't cracked.
Now there were a couple of fertile points in the article that could bear more development in another piece.
1. An RFC sometimes focuses on the sender, without then turning to the receiver. For example, suppose it says that the Foo header must not contain Bar. So if a sender sends a header of "Foo: Bar" then it is clearly "nonconformant." But what is the recipient to do? Ignore it, send a certain error message, what? This is especially pertinent given that the Robustness Principle advises that you "Be conservative in what you do, be liberal in what you accept from others" (https://en.wikipedia.org/wiki/Robustness_principle).
The takeaway is, I think that the IETF should work it explicitly and prominently into the RFC template. In the editor's guide or whatever for how to write an RFC, it should call out this very problem and say something like, "For every rule you lay down, be sure to address how the recipient should handle it when the sender breaks the rule."
2. RFCs should remember that readers are humans. For example, "In the example above, whitespace isn’t allowed around the semicolon, but you can bet that some people will put it there." Right. Some people will put it there because for 20 years in everyday writing they have seen semicolons followed by whitespace. It is part of being a writer to not just put your claim in "grammatical English" but also to take into consideration the reader's culture and background. You can't say, "Well, there clearly is no whitespace in the Backus–Naur form that I painstakingly laid out for you." Humans are not computers. They are not functions. They do not always return the same output for a certain input. This is because they are always entertaining several streams of input, most of which you don't have control over.