The joke RFCs are the best documentation

Every April the IETF publishes a joke RFC, a tradition running since 1978. They are funny. They are also, consistently, better written than most serious specifications, and that is worth examining.

the canon#

RFC 1149 — "A Standard for the Transmission of IP Datagrams on Avian Carriers." IP over carrier pigeon. Specifies encapsulation, MTU, and the failure characteristics. Notably: it was actually implemented and tested in Bergen in 2001, achieving a 55% packet loss rate and ping times measured in hours.

RFC 2324 — the Hyper Text Coffee Pot Control Protocol, which gave the world HTTP 418 "I'm a teapot." Still returned by a nonzero number of production servers and still occasionally proposed for removal, which reliably generates more discussion than any real feature.

RFC 1925 — "The Twelve Networking Truths." Not a joke, exactly. A list of things that are simultaneously funny and among the most useful engineering aphorisms ever written:

(3) With sufficient thrust, pigs fly just fine. However, this is not necessarily a good idea.

(6a) It is always possible to add another level of indirection.

(11) Every old idea will be proposed again with a different name and a different presentation, regardless of whether it works.

Number 11 is the most predictive sentence in computing.

RFC 748 — TELNET RANDOMLY-LOSE Option, the first April Fools RFC, which parodied the specification format so precisely that it reads as a real document until you notice what it specifies.

why they are well written#

Here is the thing: a joke specification only works if the reader can follow the technical content exactly. The humor lives in the gap between rigorous form and absurd content, and the gap only exists if the form is genuinely rigorous.

So the author cannot hide behind jargon. Cannot be vague. Cannot leave the failure modes unspecified, because the failure modes are the joke.

RFC 1149 specifies the MTU, the encapsulation, the retransmission behavior, and the security considerations. It is a more complete specification of a transport protocol than a lot of real protocol documents, in one page.

what to steal#

Specify the failure modes. The joke RFCs always do, because failure is funny. Real specifications frequently do not, because failure is embarrassing. Failure is also the part your implementer most needs.

Be short. Every one of these fits on a page or two. Length is not thoroughness.

Use concrete examples. The absurd ones are memorable; ordinary concrete ones are just as clear and less funny, which is fine.

Write the security considerations section honestly. RFC 1149's is a single sentence about the possibility of the carrier being intercepted by a predator. It is more informative than a great many real ones, which say "security considerations are out of scope for this document" — a sentence that should be banned.

the serious point#

Technical writing quality is not about vocabulary or formality. It is about whether the reader can reconstruct what you meant.

The joke RFCs are readable because their authors were writing for an audience they wanted to make laugh, which requires being understood. Most specification authors are writing for an audience they want to satisfy, which does not.

If you want to test whether your specification is clear, hand it to someone and ask them to implement it without asking you a question. Every question they need to ask is a defect.

The pigeon RFC would pass that test. Most of what I have written would not.

the tradition#

It continues, annually, and it is one of the better things about a standards organization that could easily have become entirely humorless.

An institution that can laugh at its own form is one that understands the form is a tool rather than a ritual. That is worth more than it sounds.