by Darius Kazemi, December 30 2019

In 2019 I'm reading one RFC a day in chronological order starting from the very first one. More on this project here. There is a table of contents for all my RFC posts.

Our documentation sucks

RFC-364 is titled “Serving Remote Users on the ARPANET”. It's authored by Marshall D. Abrams of the National Bureau of Standards and dated July 11, 1972.

The technical content

Abrams starts this RFC by enumerating the two biggest problems on the ARPANET:

  1. remote hosts being offline a whole bunch
  2. end users having absolutely no idea what to do once they're connected to a remote host

Basically, most ARPANET sites require you to already know how to use their software in order to use their software. Their software is either not documented, or hardly documented. As of July 1972, the most efficient way to learn to use an ARPANET Host is to fly to a Network Working Group meeting and spend time face-to-face with the people who work at that host site.

Abrams is critical of the ARPANET Resource Notebook, which is the main printed and disseminated documentation for users, which he finds unacceptably high-level. He provides something like 50 additional questions that he would like the Notebook to answer regarding each site.

And he's right, all of this documentation would greatly increase the utility of the ARPANET to users who aren't also the actual architects of the entire system.

Further reading

Similar complaints come in RFC-369, where the author says, re: using the ARPANET:

By far the most annoying difficulty was obtaining adequate documentation.  The resource notebook was found to be interesting but of limited utility.

The Resource Notebook (I can't find a 1972 edition right now) will eventually morph into the ARPANET Resource Handbook. The 1978 edition I've linked weighs in at a whopping 1026 pages.

How to follow this blog

You can subscribe to this blog's RSS feed or if you're on a federated ActivityPub social network like Mastodon or Pleroma you can search for the user “@365-rfcs@write.as” and follow it there.

About me

I'm Darius Kazemi. I'm an independent technologist and artist. I do a lot of work on the decentralized web with ActivityPub, including a Node.js reference implementation, an RSS-to-ActivityPub converter, and a fork of Mastodon, called Hometown. You can support my work via my Patreon.