Down the Rabbit Hole: Drink Me, Eat Me, README

Every software project has one. It's easy to scroll past. Most of the time it's just a manual telling you system requirements, installation steps, and known bugs.

But the README file owes a debt to Lewis Carroll, and a quiet trick built into its name that has been manipulating computers for decades.

In this episode, we follow the README from its earliest appearances through the conventions that made it a standard, and to the programmers who decided it could be much more than documentation.

In this episode

• Alice's Adventures in Wonderland - the literary origin programmers point to as inspiration
• The ASCII trick - the quiet reason README is written in all capitals
• The printer in the woods - a README that went somewhere unexpected

Further reading

• README file entry in the Jargon File

Episode Music

• "Dasein" by James Opie / Nihilore, CC BY 4.0
• "Scarecrow" by James Opie / Nihilore, CC BY 4.0
• "Found Poetry" by James Opie / Nihilore, CC BY 4.0

Transcript

0:22

Imagine being Alice at the bottom of the rabbit hole. You've landed in a hall of locked

doors nothing makes sense. The rules of the world you knew have been replaced by something arbitrary and strange. You are profoundly lost, and then you see the glass bottle. Tied around the neck of this bottle is a paper label and printed on that label in large beautiful letters are two words: 0:30

drink me It doesn't tell you what's inside. It doesn't say shrinking potion. It just tells you what to do. It is a hand reaching out in the dark, offering a way forward when you have no idea where to begin. When the first computer programmers started building their own strange arbitrary worlds, they realized they had a very similar problem. They were writing software, saving it to massive spools of magnetic tape and handing those tapes to other people. But when you loaded that tape, you were just staring at a sea of files, a labyrinth of code. You were Alice, standing in the hallway, looking at a hundred locked doors. The people writing the code needed a way to leave a note for whoever came next. And they knew exactly who to steal the idea from. I'm Daina Bouquin. and this is Lore in the Machine. If you look in the jargon file, the successor to that dictionary Peter Sampson started for the Tech Model Railroad Club, the one we talked about in our first episode, if you look in the jargon file, you will find an entry for the readme file. This dictionary calls it a hacker's eye introduction. and notes that

that if you ask early programmers where the convention came from, they will invariably point you right back to Lewis Carroll, to Alice, and the magic munchies labeled Eat Me and Drink Me. But these programmers didn't just borrow the concept. They weaponized the alphabet to make sure you couldn't miss it. They decided the file had to be written in all capital letters: 2:30

README. This wasn't because they were shouting It was a brilliant, quiet manipulation of the machine's own rules. Because computers sort things using the ASCII encoding standard, and in ASCII, uppercase letters are assigned values that come before lowercase letters. The jargon file pointed out that, quote, by ancient tradition, actual sources of code were written in lowercase. So when the machine sorts a directory of files alphabetically. The capital letters defied gravity. The README file would float past all the code, resting at the absolute top of the list, waiting for you. The earliest README I've found was left like a message in a bottle on the day before Thanksgiving in 1974. A programmer named Ashley Grayson was saving some circuit analysis programs onto a fail-safe tape. They wrote out a text file detailing the system requirements, explained how the programs were broken into parts, and signed off simply, good luck! Then left their name. Over the decades, as the internet grew and software became something distributed to millions, those files became standard. Most of the time, they are purely pragmatic. They hold copyright info, known bugs, or installation instructions. But sometimes they are something else entirely. Sometimes they are a place where a programmer, sitting alone in the glow of a monitor, decides to leave a piece of their soul behind. Years ago, a Linux user downloaded the source code for a tool called gnome-cups-manager. It was a profoundly boring piece of software, an interface for managing printer cues. They opened the readme file expecting to find dry technical notes. Instead, they found an entire fairy tale. The file began. Once upon a time, there was a printer who lived in the woods. Now this story tells of a lonely printer, sad because nobody knew how to configure him. He asks the wind to be his friend, but the wind just says whoosh. He asks the rain, but the rain just says pitter-patter. The little printer spends his days inside, sobbing, jamming his paper, and blinking his lights cryptically, because that is what little printers do when they are sad. Until one day, a little girl named gnome-cups-manager stumbles into the clearing, and agrees to be his friend. And the file concludes. The printer was happy. He spent the rest of the day playing games and printing documents, for that is what little printers do when they are happy. Sometime soon, you might find yourself browsing GitHub looking for a piece of code. You'll click on a repository, and right there on on the front page, automatically rendered in large text, will be a file called readme.md. It is easy to look past it, to see it as just a manual. But when you read it, you're stepping into a tradition born in the 1970s, a place where developers can remind you that they're human. And you're reading the words of someone who built a maze but wanted to make sure you didn't get lost inside it. You're standing in the hallway and someone is handing you a bottle. Read me. I'm Daina Bouquin and this is Lore in the Machine.