Why Developers Don't Read Your Documentation

Developers never read your documentation. They ctrl-F, skim for a code block, copy it, and bail. If the code block doesn't work on the first try, they leave. If the page takes more than two seconds to load, they go back to Stack Overflow. The average developer spends less than 90 seconds on a docs page, and most of that time is spent scrolling past the introduction you spent two hours writing.

This is not a failure of your docs. This is how developers work. The failure is assuming they read anything.

I've spent the last year watching session analytics on developer docs across a lot of customer sites and reading through every documentation best practices playbook to see which ones match the data, and the pattern is almost comically consistent. A developer lands on a page from Google. They hit ctrl-F. They type a function name, an error string, or a noun. They find it or they don't. They leave. The "time on page" metric is not time spent reading. It's time spent deciding whether to close the tab.

Once you accept this, a lot of advice about writing documentation stops making sense. "Write a great introduction" becomes "write introductions nobody reads." "Explain the concepts first" becomes "bury the code the developer came for." The standard playbook is built for a reader who doesn't exist.

The 90-Second Rule

Here's the frame I use when looking at a docs page. Imagine a developer arriving from a Google search for a specific error message or API call. They have 90 seconds before they context-switch back to Stack Overflow. In those 90 seconds, they will do exactly three things: search the page with ctrl-F, look at the first code block, and check if the output matches what they expected.

That's it. They will not read your "Welcome" section. They will not read the "Overview." They will not read the paragraph that sets up the example. They will read the example, and only if the example breaks will they go back and read the paragraph to figure out why.

If your docs page doesn't survive this test, it doesn't matter how well-written the prose is. Nobody is reading the prose.

The Sites That Get It

Stripe is the canonical example, and not for the reason people usually say. Everyone points at Stripe and says "great design." The thing Stripe actually gets right is that every page leads with a working code block. You land on the charges API reference, and the first thing you see is a curl command you can copy. The prose explaining what a charge is comes after the code, not before it. The developer who already knows what a charge is gets the code and leaves. The developer who doesn't know scrolls down and reads. Both are served.

Vercel does something similar with tabbed code examples. You land on a page, the example is right there, and you can switch between Next.js App Router, Pages Router, React, Remix with one click. No lecture about which framework to pick. The assumption is you already picked one and you just want the code.

Supabase goes further. Their auth docs include inline runnable snippets where you hit a button and see the actual response. The developer doesn't have to copy code, wire up credentials, run it, check the output. They get the output on the page. That collapses the 90-second test into about 10 seconds.

Linear's docs are the counter-example that proves the rule. They're beautifully written and genuinely worth reading end-to-end. But Linear is not a developer tool in the same way Stripe is. Most Linear users are PMs and founders who actually do want the conceptual overview. Match the format to the reader.

The Counter-Argument

The strongest pushback on this view is that good conceptual documentation builds loyalty. Readers who understand the system deeply become advocates. A terse reference-only site can't do that. There's a real grain of truth here. Stripe's success is not just the code-first pages; it's also the long-form guides on subscription billing and SCA compliance that help developers who want to go deeper.

My answer is that conceptual docs and reference docs serve different moments, and you should stop putting them on the same page. Reference pages should assume ctrl-F. Concept pages should assume a reader who came specifically for the concept. When you mix the two, both suffer. The developer searching for an API call has to scroll past a lecture, and the developer who wanted the lecture is distracted by a wall of code.

Split them. Make your reference ruthlessly scannable. Make your concepts proper essays. Link between them, but don't blend them.

What Actually Works

A few things that consistently help, in rough order of impact:

1. Put the code block above the prose. Always. If a developer arrives and has to scroll, you've already lost most of them.
2. Name functions and error messages the way developers will search for them. If your error says "Invalid credentials," don't put a page titled "Authentication troubleshooting." Title it "Invalid credentials." That's what they'll ctrl-F.
3. One page per question. Not one page per concept. If developers ask "how do I upload a file," make a page called "Upload a file." Don't bury it in a 6000-word "File handling" page.
4. Working examples over complete examples. An example that's missing edge cases but runs on the first copy-paste beats a fully-hardened production snippet that takes imports from five files.
5. Skip the "getting started" tutorial that doesn't actually get anywhere. The pattern of "install the package, import it, and call hello-world" wastes everyone's time. Start with the thing the developer came to do.

The real insight is that your docs are not a book. They're a reference tool that needs to work like a well-organized dictionary. People pick up dictionaries to look up one word. They don't read the introduction. They don't want to. If you design your docs for the reader who reads cover-to-cover, you've designed for nobody.

The next time you write a doc page, ask yourself what error message or function name would bring a developer here, and whether they can find it with ctrl-F in under ten seconds. If the answer is no, rewrite the page. If the answer is yes, you're done. They weren't going to read the rest anyway.

For the related question of how to structure a full docs site around this reality, see how to organize documentation and the documentation style guide piece that goes deeper on voice and format.