3 ms·
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 writi
by combatentropy 8y ago
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 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.
- deleted 8y ago[deleted]