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. ...or they tell you to dedicate a whole week to reading the documentation before onboarding yourself with any product. Can you imagine the audacity? 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? by the very people who built the thing, But that’s precisely what I’m here to fix. In this essay, I will tell you why you should absolutely never read documentation. If you’ve been reading docs before now, don’t worry, you still have time to repent. absolutely never 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? 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: literature A masterpiece of clarity, precision, and helpfulness Or a migraine-inducing incoherent compilation A masterpiece of clarity, precision, and helpfulness Or a migraine-inducing incoherent compilation 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, who in turn spend a lot of time crafting 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? good Experiences This is a true story. The events depicted below took place somewhere in my corner of the world… This is a true story. The events depicted below took place somewhere in my corner of the world… Let me take you through three completely avoidable personal incidents that led to this very opinionated piece... Because if I can’t convince you, maybe my pain will. Vue Autocomplete Several weeks ago, I was working on a Vue project and had the most interesting time (re)using the Vue Autocomplete package. interesting 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. 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 lessons? 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. something Android documentation This was particularly mortifying, so I won’t dwell too long here. I leave to your imagination, my pain. Fool me once, strike one. Fool me twice, strike three… Fool me once, strike one. Fool me twice, strike three… 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. Stack Overflow 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. exist in the AI future 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 are frustration and every other emotion, 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. 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 ought to do. made the tool know 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 reasonable, 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. It will truthfully tell you what’s possible and what might blow up if you ignore a certain parameter. documentation is your friend 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 tools 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? If you’ve read this far, you’ve already broken the first rule: You read something. 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 is more than 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.
