Originally drafted as a thread on hackers.town, after Abbie Normal asked me to expand on a side comment in a discussion of documentation.

There’s a story old Unix beards tell about how they learned Unix. We just read all the manpages, they say, that’s how well written they are, you don’t need to read anything else or take any classes. Maybe also pick up a copy of K&R if you’re a little iffy on C.

I consider myself an old Unix beard, even though I don’t have a beard and I only got into the game in the days of SunOS 4.1, and until quite recently I thought this was how I learned Unix. I did read all the manpages, without any formal coursework, and trained myself up as a programmer to the point where I could get a job in the industry. It took three years of self-study and experimentation, consuming nearly all my free time, and in retrospect I wouldn’t recommend the experience, but, y’know, it worked out, right?

But the thing is, this story completely neglects all the things I’d already learned about computers and programming before I got to college.

As a kid I read every single book in the house, indiscriminately, no matter how boring it would seem to an adult—including a bunch of old computer science textbooks that we had for some reason. And I spent a bunch of time tinkering around with computer programming, mostly not on Unix and not in C, but still. When I came to the manpages I had the beginnings of a conceptual structure for understanding systems programming in my brain already.

I realized this only because of the experience I’ve had over the past two years in teaching computer science—specifically, CMU’s Introduction to Computer Systems course, which, at first glance, seems to have a lot of overlap with the content I used to think I learned from the manpages. But as I repeat the lessons for each new batch of undergraduates, and especially as I spend time helping them with the specific things they get stuck on, I’ve come to realize that what I’m actually teaching is the stuff I already knew when I started reading the manpages. And, also, that I would not have been able to get much out of the manpages if I hadn’t already known that stuff.

So, okay, why does it matter that I didn’t learn my trade the way I thought I did? Because, first, holding up the manpages as ideal documentation is a mistake. They are pretty darn good reference documentation within their domain, and that’s why they appeal so much to experts: if you already know most of what there is to know about a standard C library function, or a Unix shell command, and you just need a bit of a reminder on how to do one specific thing, the manpages will not let you down. Reference documentation for other languages and tools is often frustrating by comparison. But, if you don’t already know, if you don’t have the concepts and the mental models, reference documentation is not what you want. Instead you need a guide, or a textbook.

(I did read lots and lots of guides and textbooks, before, during, and after those three years of self-study and experimentation. I’d expect that most of the people who call themselves Unix beards had done the same. In retrospect, I got so much more out of Starting FORTH and TCP/IP Network Administration and the Lisp 1.5 Primer and some 1975-vintage algorithms textbook whose name I can’t remember (all the examples were in Pascal) than I ever got out of the manpages.)

The people who insist that the manpages are all you need will sometimes dismiss guide-type documentation as tedious to work through; they’d rather learn things from a reference, they say, because that way they can jump around in it and look for the specific bits that are relevant to them right now. And that’s fine—if they’re right that the stuff they’re skipping over isn’t relevant to them. But it also has negative practical consequences.

If you are in the habit of reading only the bits of the documentation, whatever documentation you have, that you think are relevant right now, you’re liable to come away with a mental model that’s only vaguely accurate; possibly dangerously in‌accurate in places. (I think this is a lot of why the user commentary at the bottom of the online PHP documentation is so full of bad advice.) And, if you are only interested in reference documentation yourself, you’re probably not going to try to write guides for the software you yourself write. (This is how we get monstrosities like the Git documentation, that are only of any use to someone who already knows how it works and just needs a bit of a reminder.)

Furthermore—this isn’t just about bad documentation. When experts repeat inaccurate stories about how we learned to code, we’re setting the next generation of hackers up to fail to learn to code. The Jargon File, which records how the generation of programmers before mine thought they learned to code, holds up the experience of devoting all of your free time to learning computers as necessary:

larval stage n. Describes a period of monomaniacal concentration on coding apparently passed through by all fledgling hackers…the ordeal seems to be necessary to produce really wizardly (as opposed to merely competent) programmers

This may have seemed to be true when it was written (although I believe I smell a variation of the sunk cost fallacy at work) but it doesn’t leave any room for people who don’t learn things by monomaniacally concentrating on them. (This is not the only place where the Jargon File’s authors failed to imagine how people whose brains worked differently than theirs could be any good at computers.) I’m pretty confident that someone who practices programming strictly as a hobby, less than ten hours a week, will eventually get just as good at it as one of these fledgling hackers who doesn’t do anything else with their spare time. And, if we tell people that, they won’t get put off the subject by the unappetizing prospect of not getting to hang out with friends on the weekends.