Read the docs like a book

I thought when I worked at bigger tech companies it would be different. You are legit top 1% if you RTFM - @Ryan_Magoon

One of my long-held beliefs is that the easiest thing you can do to advance your career is to sit down with the documentation for your favorite tool and read it straight through. Front to back, cover to cover, like a book.

YouTube is great.

Courses are great.

Blog posts are great.

But all of those serve a fundamentally different purpose than reading the docs straight through.

Reading the docs increases the efficacy of all the things listed above. It's fundamentally different, and it's a force multiplier.

You may think that there's no way you could remember everything in the docs anyway, so why bother? The point of reading the docs straight through isn't actually for you to remember everything, so you can free yourself from that pressure!

In my experience, reading the docs provides two primary benefits:

it establishes a mental map of the territory
it primes your subconscious

Establishing a mental map

A common rebuttal to reading the docs is that it's easier and more efficient to just look up issues when you have them.

Looking up solutions as you have problems is great! This only works for specific, discrete problems, though. Usually that means problems with error messages attached or problems in the shape of "How do I do [x] thing in [y] framework?"

Those are the problems you know you have.

There is another set of problems that you don't even know you have. This is what reading the docs solves for.

There are features that you didn't know about.

You're reinventing things that are built-in to the language or the tool.

Some optimizations are freely available to you that you never knew existed.

As you read the docs, your mind generates a map, populating it with signposts.

You may learn that MySQL has robust support for JSON documents, including indexing, by reading the docs. That's great, but you don't need to remember how JSON indexing works! All you need to remember is the vaguest notion that MySQL has some sort of JSON support. The next time you encounter a JSON-performance-in-MySQL-shaped problem, you'll think, "hey... I read something about this. Lemme look that up again."

That's the desired outcome. Just that!

When you have a race condition in your Laravel app, part of your brain will light up and whisper "atomic locks." Then, you can return to the documentation with a discrete problem in mind and dive deep into the details.

Diving into the details

When diving into the details, you'll go deeper much more quickly, because of your broad base of understanding. Having breadth allows you to draw connections and make inferences across the entire body of the project.

The parts of the docs that don't directly apply to what you're doing now merely populate the mental map, which will be helpful later. However, there are parts of the docs that do apply to what you're doing right now!

When you get to a section of the docs that relates to your current scope of work, your brain will draw that part of the map in intricate detail because you're already primed with context. You'll get so much more value out of that section because you're already familiar with the terrain, and now you're filling in all the little details.

ChatGPT has the answer

But, unfortunately, you still need to know what the question is.

If you are unaware of a topic's existence, how will you coax it out of GPT? The unknown unknowns still present a problem! You don't know what you don't know.

Once you know the universe of topics, you can use GPT to go deeper on specifics. (Whether that's a good idea or not is a topic for another blog post. I think it mostly is!)

The map is essential, but there's a secondary, underrated benefit of reading the docs straight through, and it has to do with how your brain processes information.

Priming your subconscious

The reticular activating system (RAS) is a network of neurons in the brain stem that filters out noise from information. It's the reason you can hear your name clearly when it's spoken softly in a noisy room. Your name is important information, so your brain is attuned to it.

Have you ever learned a new word, and then suddenly, it seems like that word pops up everywhere for the next week? That's the RAS! The word was previously noise, totally filtered out. Now it's signal, because you just learned it. It has meaning now.

Have you ever gotten a new car, let's say it's a Jeep, and then noticed that somehow every car in the world is a Jeep? Of course, the number of Jeeps didn't change. You just didn't care. Your brain is being pummeled with makes and models of vehicles all day, every day, so it just filters them out. But when you get a Jeep, it becomes important signal for a little while.

Reading the docs absolutely fills up your brain with new signal. Maybe you don't understand all the details, but that's fine! Your brain is now tuned in to a whole new universe of information that was previously whizzing by you, undetected.

When you're scrolling Twitter and see a tip or trick you may have previously missed, your brain wakes up and says, "Hey! Those words look familiar! I've seen words like that before!"

If you asked me to scroll Medical Twitter or Law Twitter for an entire day and give you my takeaways, I'm not confident I'd come up with anything. My brain simply has no context for the stuff they're tweeting. It all looks like noise to me. There's no bucket, no slot for the information to go, so it falls straight through.

Reading the docs gives your brain new context, new buckets to catch information. It strings the first strands of a web to catch knowledge that was out there all along, flying right by you.

Everything becomes more profitable! Podcasts, blog posts, conversations with coworkers, Hacker News comments, courses, YouTube, error messages. There are more chances that something you read or hear is going to stick to one of the strands.

Reading the docs prepares your brain to catch more details later.

How to read the docs

I prefer to read them on paper. I got two chapters of the MySQL docs printed and bound and read through them.

The medium is up to you, but reading them with zero pressure to remember anything is the key. Your brain will do the hard work. If you put too much pressure on yourself to memorize everything, you likely won't even start.

I like to read through them and highlight anything that makes me go, "huh, neat!" and then just keep moving. If there are big sections that get super boring, I'll start skimming.

Read them in one sitting, or don't. Read a few pages for a few minutes each day, and you'll soon be the most knowledgeable person on your team, maybe in your whole company.

Reputable books can stand in for cases where the docs are literally thousands of pages. I've read several good books on MySQL and then printed two of the more important chapters from the docs (data types and optimizations). Even those two chapters were several hundred pages. I flipped every page but did not read every word on every page! The more of the actual documentation you can read, the better.

Reading the docs is selfish

I can tweet and blog all I want about how reading the documentation is good, and still, vanishingly few people will read the docs. Many of the replies to my original tweet were "I don't have time" or "I don't get paid to read the docs."

I totally get it. My wife and I have two-year-old twins and twins that are due in one week. Time is precious.

My response is simple: reading the docs is purely a self-interested pursuit, and I can always find time to do things that make my life better.

I want to do my job better and faster. I want to get promoted. I want to get paid more. I want to get hired. I want to make better content. I want people to think of me as an expert. I want the deep satisfaction of mastery.

I want to get ahead, so I read the docs. Most people won't. But that's what makes relative advantages work!

Some people will do it, but most people won't.

As a YouTube video

If you'd like to watch this on video, I made it into a YouTube video!

Other people's stories

Here is a short list of people echoing the sentiment in response to my original tweet. I found some of them fascinating. Hope you enjoy them.

reading the docs front-to-back is not about memorizing or even remembering what’s in the docs. it’s about setting up a bunch of neural tripwires to make you think, “wait, I feel like I’ve seen a way to deal with this before” when you hit a problem - @jlengstorf

I worked with a guy who was so damn good at uncommon things, like shell scripting. Finally asked him how he got so good at that: "I read the bash manpages front to back every three months." Inspired me to go deep on the SNMP RFCs (I ran a NOC at the time), which paid dividends - @mike_julian

Studying the source makes you more creative. You can make your own connections and insights as to how to use the information. Starting from tutorials limits you to someone else’s creative limit. - @jdnoc

Specs, too. A specification is just "the docs" for a language or protocol. Just read it straight through. It's an investment that pays dividends for a very long time. - @izs

Because there’s little things that then stick in your mind because they apply to your specific use case. But if you weren’t looking for it, you wouldn’t find it. So I’m all in on team read all the docs - @JackEllis

My general advice is when you start a new thing, read the docs through. Then start. You’ll forget 75+% of it but the high level remains and you know it exists so you can go find it when it matters. - @cameronolivier

My company asked me to create a training and merit course for the framework we use heavily. Step 1 was RTFM. They are even really well maintained docs! Only 2 of us ever completed the course.

I got poached to another company as an expert in that framework so... @ub3rh4xor

Reading docs front to back is often boring af, but most of the time the invested effort pays off very shortly. That's my experience too, after 30+yrs - @onetom