by Darius Kazemi, December 30 2019
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:
- remote hosts being offline a whole bunch
- 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.
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 “@firstname.lastname@example.org” and follow it there.
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.