This is a card in Dave's Virtual Box of Cards.

RTFM: Read the (Friendly) Manual

Created: 2022-10-07

In the beginning, books

Back in my day, all we had were books and we were lucky if Addison-Wesley or O’Reilly or even Wrox had published something on the subject!

I still prefer a book (made of paper!) for learning new subjects. I can put sticky-notes in them, I can read them on the couch. Good ones invite reading cover-to-cover and give me the sense that I’ve learned everything the author intended for me to learn (which gives me the sense that I’m probably not missing anything super important).

Things used to have manuals

Like, printed ones. Man, those things were beautiful. But in a lot of ways, that was only possible because the old stuff was so much simpler and more predicatable than some of the stuff we have to deal with now. Can you imagine trying to come up with a manual for a modern home computer? I mean more than just the glossy "plug it into the wall, enjoy!" stuff we have now. I’m talking about the schematics and CPU instructions and tour of the OS (notice I said the OS)…​

Applications came with thorough guide books. Now, you’re lucky if you can find a video.

Things still have manuals

Okay, they don’t print them anymore, but for a lot of things, the manuals totally still exist.

Here’s why you should read them:

  1. You’ll know what’s possible

  2. You’ll know where to find the answers

  3. With any luck, you won’t have to search the Web to get your answer

The Web search for "how do I X" probably won’t also clue you into "Y" and "Z". Reading (or skimming) the whole manual will.

There’s an additional benefit and I think it’s backed up by Real Brain Science:

The act of actually trying to remember something you’ve read about and then searching for it in a manual, I’m convinced, is a way better memory booster than just looking up the answer on the Web. Do it the hard way a couple times and I believe you’ll start to remember it. Resist the easy path for a bit and see what happens.

Offline copies of docs are definitely faster if you know where they are and roughly what you’re looking for.

The Web

I have to admit that for quick reference, the Web is often the fastest answer.

The Web also contains more obscure edge-case stuff that couldn’t possibly fit in a book. So you pretty much gotta search for it and hope somebody’s already asked on StackOverflow.

I can’t count how many times I’ve given up with :help foo and :help bar in Vim and finally just searched "how do I foobar in vim?" on the Web. If you don’t know exactly what you’re looking for, offline docs can be a real pain.

But the Web is also a massive distraction. You gotta get your answer and get the hell out of there before you lose the drive to build your own stuff and just read about other people’s stuff.

Also, increasingly, I’m finding that Web searches aren’t returning quality answers from the official project documents, but super low-quality ones from ad-driven websites spamming the web with garbage. If you’ve gotta use the Web, you’re probably better off bookmarking the official docs and hoping they’re easy to navigate/search.