Why You Should Never Read Documentation
You’ve heard it before: “The best way to get started with any product is to start with the documentation.”
Some might even go so far as to suggest that documentation is better than Google or Stack Overflow.
...and when I thought I had seen it all, I am now told that you ought to dedicate a whole week to reading docs! Who has that time?
Can you imagine the audacity?
Suggesting that carefully written, structured, accurate material, designed by the very people who built the thing is somehow more useful than vibes and blind optimism?
But that’s precisely what I’m here to fix.
Today, I’m going to tell you why you should absolutely never read documentation. And if you’ve already been reading docs before now, don’t worry, you still have time to repent.
You are probably tired of hearing opinions, but you should listen to me as I speak from experience, and what better teacher than someone else's experience?
What is documentation, anyway?
Before I dump my opinions on you, let’s go over what documentation really is.
Documentation is a form of literature and like all literature, it can either be:
- A masterpiece of clarity, precision, and helpfulness
- Or a migraine inducing incoherent compilation with broken links
But why do you need that when you can just keep tweaking things until something works, or doesn’t? Or maybe even ask any of the general-purpose LLMs out there.
Companies pay technical writers good money and spend a lot of time crafting a great documentation. You might wonder why they bother when we all should just fumble around and figure things out ourselves. How tough can it be?
Enough preambles; let me tell you about the experience that led to this very opinionated piece.
Experiences
“This is a true story. The events depicted below took place somewhere in my corner of the world…” - modified and adapted from the movie Fargo
Let me take you through three completely avoidable incidents from my life. Because if I can’t convince you, maybe my pain will.
Vue autocomplete
Several weeks back, I was working on a Vue project, and I had the most interesting time (re)using the Vue Autocomplete package.I first used this package about 3 years ago in the same project, and in a twist of luck, I had to revisit it to make some changes.
I set to work. Of course, I didn’t revisit the documentation. I didn’t even remember there was documentation!
See, if no one remembers the documentation, why write any?
So I made the necessary code changes. It broke!
I tweaked it. It broke more!
I sacrificed my sanity. It stayed broken!
I visited Google. No solution!
Why am I having trouble with this simple update, I asked. Something must be wrong somewhere, but not with me.
As a last resort, I visited the documentation, and there was my solution, sitting pretty.
Time wasted? Let’s not think about it.
Docs’ reading time? Less than a minute.
Regrets? Argh, let’s not talk about it.
Of course, I could have spared myself the headache and used my time better if only I had started from the documentation. But well well well...
Did I learn any lesson? Of course not!
The Android project
While working on an Android project, I spent an embarrassing amount of time figuring something out when I could have started with the Android documentation.
This was particularly mortifying, so I don't wanna dwell too long here. I hope you understand my pain.
The AI that lied
Now the last one!With the many general-purpose LLM solutions like ChatGPT and Gemini available, which have reduced developers' reliance on Stack Overflow and even Google searches for resolving errors, I'm not alone in my reluctance to read documentation.
I often think the best thing to do is to ask these multipurpose AI solutions to offload the documentation to me.
So how did that pan out for me?
I was playing/getting onboarded with Redis, but I thought I'd task ChatGPT with that. And you know what ChatGPT gave me back as responses?
Hallucinations! Premium Hallucinations! It told me things that didn't exist in Redis. However, I am not alone in experiencing this; it seems the hallucinations already exist in the AI future, and we(the present) just need to catch up.
So..., after wasting precious time and burning, who knows, the equivalent of how many trees, I went to the Redis documentation and got myself properly acquainted.
Problem solved.
Now what?
I know with these experiences, it seems like a no-brainer to read documentation, but just wait till you read my ironclad, bulletproof reasons on why you should avoid documentation at all costs.
1. Time is an illusion
We’ve all been taught that “time is precious.” But what if that’s all wrong?
I mean, this wouldn’t be the first time we’ve believed in something false; we once vehemently believed the earth was flat (and some people still do).
What if our understanding of time has been wrong all along, and we've needlessly subjected ourselves to the terror that “time and tide wait for no one,” when in fact, it does!"
Maybe time is an illusion, and there’s no such thing as “wasting” it.
So you spent 3 hours fixing a 2-minute problem because you neglected the documentation, so what? You were “experimenting.”
And as we all know, great inventions come from experimentation.
2. Frustration builds character
What is frustration and every other emotions, if not a social construct?
A little frustration is good for the soul. If problems make you stronger, then frustration builds your resilience.
The minor frustration of trying to solve a problem because you refused to read the documentation is nothing compared to the frustration of inflation and the rising cost of living. So embrace it!
Reading documentation robs you of that precious growth.
Want to be resilient? Suffer more.
3. You know more than the creator
Why read a guide written by the people who made the tool? You’re the user. You know what it should do.
Docs just get in the way of your genius.
4. AI knows everything
AI can solve all your problems. Even if the documentation doesn’t exist or the AI hasn’t been trained on it, they can hallucinate a perfectly reasonably sound, completely made-up method for you and bring the feature into existence.
But seriously…
I've finally broken free from the chokehold of doing everything but reading the documentation, and I've learned some important lessons.
The first is that documentation is your friend (not the same way they say “police is your friend”). It will truthfully tell you what’s possible and what might blow up if you ignore a certain parameter.
It’s the ultimate source of truth for getting onboarded to any product, and when you can get the truth directly and free from the source, why would and should you trust anything else?
Remember those earlier tweets telling you to “start with the docs” before trying a new tool or to “read the docs” for debugging? They weren't lying. They're gem-level tips worth sticking on your whiteboard so the next time you’re building or debugging, you know exactly where to start.
And now to my favorite part about using AI, not the company-trained AI integrated into tools and documentation, but the general-purpose models like ChatGPT or Gemini.
These tools are excellent for generating boilerplate code, explaining well-known concepts, or brainstorming ideas. But their accuracy is limited by the data they were trained on.
Just as the law of conservation of mass-energy tells us that you can’t create something from nothing—only transform what’s already there—AI can’t generate truly new knowledge from a void. It reshapes and rephrases based on the patterns it already knows.
So, when an AI hasn’t been trained on a recent development or unfamiliar topic, it can’t deliver facts; it can only guess, often with misplaced confidence. In essence, AI isn’t a source of knowledge or a replacement for documentation; it’s a mirror of what it’s been given.
So, you’re better off starting with the documentation. If you get the wrong info there, you can reach out to the product creators, but who are you going to hold accountable when Gemini hallucinates a command that doesn’t exist, or never will?
TL;DR
Who adds a TL;DR at the end of the piece? Well, I just did!
If you've read this far, you've already broken the first rule: You read something.
And for that, I commend you.
So maybe, just maybe, you’ll also read your next project's documentation.
Not all of it. Not at once. But enough to avoid burning days, trees, and your sanity.
Because in the end, documentation isn’t just a technical resource.
It’s the cheat code to working smarter, not harder.
I hope with these few points of mine, I have been able to convince you and not confuse you that reading documentation is for chumps...
Unless you want to actually solve things faster. Then... yeah, go read it.