For a lot of libraries, I read the source before I read the docs

I'm going to say something that has gotten me side-eye in every code review I've ever done.

For a lot of libraries, I read the source before I read the docs.

Not because I think I'm too cool for docs. I'm 46 and pretty tired. I'm optimizing for "stop debugging at 11pm on a Thursday," which is a different thing than optimizing for being clever. Docs answer the question the author thought you'd ask. Source answers the question you actually have.

Some specifics so this isn't just vibes.

The retry library that lied about jitter

Last quarter we had a job that was hammering an upstream API on backoff. The docs for the retry library said "exponential backoff with jitter, configurable." Cool. We set jitter to 0.3 expecting standard decorrelated jitter, the kind you'd write yourself if you read the AWS blog post from 2015.

The library's source had about forty lines of retry logic. The "jitter" parameter was multiplied against a single random number generated once at construction. Once. So every retry from a given worker used the same jitter ratio. We had two hundred workers all using the same seed strategy and they were stampeding in lockstep.

I would have found that in twenty minutes of reading source. I lost a day and a half reading docs, posting on a forum, and convincing myself I was holding it wrong.

What the source actually tells you

When I open a file in node_modules or site-packages, I'm usually looking for a few things.

First, how big is this, really. If the "engine" is 300 lines and half of them are TypeScript ceremony, my confidence in the abstraction is different than if it's 12,000 lines of clever metaprogramming. Both are fine. I just want to know which one I'm signing up for.

Then I look at error paths. Docs love the happy path. Source tells you what happens when the input is null, when the network blips, when the config key is missing. I scan for throw, catch, raise, and for any function with the word "default" in the name.

Defaults are honestly the biggest one. Half the bugs I chase are because some library defaults to "be helpful" in a way that's wrong for my context. Pooling, timeout, retry, "auto-reconnect" — the README never quite spells these out and the API reference makes you click through six pages to assemble the picture. The source file has them in one place.

I'm not anti-docs

I'm anti the assumption that docs are the ground truth. Code is the ground truth. Docs are a translation. Sometimes a very good one. The Postgres docs are scripture. The Go stdlib docs are honestly better than the source for understanding intent. But for the random Express middleware your coworker installed in 2021, the source is faster than spelunking through a doc site that hasn't been updated since the rewrite.

The trick that made this practical for me is just installing the editor plugin that lets me jump to the actual file with one keystroke. In VS Code it's "Go to Definition" but pointed at the real installed file, not the type stub. In neovim I've got it bound to gd. Once jumping into node_modules costs me zero friction, I do it constantly. If it costs me three clicks I'll keep reading the doc site instead.

When I do read docs first

I'll be honest about the asymmetry. I read docs first for anything where the wire protocol matters. HTTP clients, database drivers, queue clients. The behavior at the network boundary is what I actually need, and source won't tell me what the server expects.

Same for new languages or runtimes. Source reading without context is just noise. And for anything with a real config story like Webpack or Kubernetes or Terraform, the source is too sprawling to start there.

For everything else, especially the 400 transitive dependencies you didn't choose, the file is right there. Just open it.

The actual ask

If you're new-ish, try this once. Pick a library you use every day and don't really understand. Open the entry point. Read the main file. Don't try to understand everything. Just see how big it is and what the shape is. You'll probably learn more in 15 minutes than from a week of skimming README.

I'd rather know the thing than know what someone wrote about the thing.

What's a library where reading the source surprised you?