“Start with the documentation.” You’ve heard it before, right? It’s practically a mantra in the tech world. Some even suggest it’s superior to a frantic Google search or a deep dive into Stack Overflow. And then there are those who dare to propose dedicating an entire week to documentation before you even think about onboarding with a new product. Can you imagine the audacity?
The nerve of suggesting that carefully written, structured, and accurate material, crafted by the very people who built the thing, is somehow more useful than vibes and blind optimism? Preposterous! Yet, here I am, not to praise documentation, but to bury it… or, well, to explore the painful joy of pretending it doesn’t exist.
You’re probably tired of hearing opinions, but you should listen to mine, because I speak from experience. And what better teacher than someone else’s avoidable pain?
What Even IS Documentation, Anyway?
Before I dump my heavily biased, yet deeply informed, opinions on you, let’s briefly touch on what documentation actually is. At its core, it’s a form of literature, much like a novel or a user manual for your IKEA furniture. And like all literature, it can be one of two things:
- A masterpiece of clarity, precision, and genuine helpfulness.
- Or a migraine-inducing, incoherent compilation of techno-jargon.
But why bother with either when you can just keep tweaking things until something works (or doesn’t)? Or, even better, why not just ask any of the general-purpose LLMs out there? It’s a valid question, especially when you consider that companies pay technical writers good money, and those writers spend a lot of time crafting great documentation. You might wonder why they bother when we all could just fumble around and figure things out ourselves. How tough can it be?
My Pain, Your Gain: Tales from the Documentation-Averse Trenches
This is a true story. The events depicted below took place somewhere in my corner of the world, moments of sheer, unadulterated head-desking frustration that could have been completely avoided. If I can’t convince you with logic, maybe my pain will.
The Vue Autocomplete Ordeal
Several weeks ago, I found myself working on a Vue project, tasked with making a minor update to a feature that used the Vue Autocomplete package. I’d first implemented this package about three years prior, and in a twist of fate, it reappeared in my sprint.
I dove in. 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 myself. “Something must be wrong somewhere, but certainly not with me.”
As a desperate, last-ditch effort, I visited the documentation. And there, sitting pretty as you please, was my solution. Time wasted? Let’s not think about it. Documentation reading time? Less than a minute. Regrets? Argh, let’s just not talk about it.
Of course, I could have spared myself the headache and used my time far better if only I had started with the documentation. But, well, well, well… did I learn any lessons? Of course not! Fool me once, shame on you. Fool me twice…
The Android Project’s Silent Sufferings
While working on an Android project, I spent an embarrassing amount of time wrestling with a specific implementation detail. The answer was readily available, just a few clicks away in the official Android documentation. Yet, I resisted.
This incident was particularly mortifying, so I won’t dwell too long here. I’ll leave my agony to your vivid imagination. Just know, it was bad. Really bad. And completely, utterly avoidable. Fool me twice, strike three.
The AI That Lied: My Redis Hallucination Trip
Now for the truly modern dilemma. With the proliferation of general-purpose LLM solutions like ChatGPT and Gemini, developers’ reliance on Stack Overflow and even Google searches has certainly diminished. I’m not alone in thinking, “Why read the docs when AI can summarize them for me?”
So, how did that pan out for me? I was playing around with Redis, getting onboarded with its various commands and concepts. Naturally, I tasked ChatGPT with the job. And what did ChatGPT give me back as responses? Hallucinations! Premium hallucinations! It confidently told me things that simply didn’t exist in Redis.
I’m not alone in experiencing this; it seems the hallucinations already exist in the AI future, and we (the present) just need to catch up. After wasting precious time and, who knows, burning the equivalent of how many digital trees, I finally went to the official Redis documentation and got myself properly acquainted. Problem solved. My faith in AI as an immediate source of factual, niche-specific information? Severely shaken.
The “Ironclad” Reasons to Avoid Documentation at All Costs (Just Kidding… Mostly)
I know, after those experiences, it seems like a no-brainer to read documentation. But just wait until you read my totally ironclad, bulletproof reasons why you should absolutely 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, they do!
Maybe time is an illusion, and there’s no such thing as “wasting” it. So you spent three hours fixing a two-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.
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. You have the visionary insight that the mere creators, lost in the minutiae of their own product, simply lack. Docs just get in the way of your genius.
4. AI Knows Everything (Even Things That Don’t Exist)
AI can solve all your problems. Even if the documentation doesn’t exist, or the AI hasn’t been trained on it, these miraculous machines can hallucinate a perfectly reasonable, completely made-up method for you and bring the feature into existence! Who needs reality when you have confident fabrication?
But Seriously… The Unvarnished Truth About Documentation
Okay, all joking aside. I’ve finally broken free from the chokehold of doing everything but reading the documentation, and I’ve learned some genuinely important lessons. The first is perhaps the most obvious: documentation is your friend. It will truthfully tell you what’s possible, how to do it, and what might blow up if you ignore a certain parameter.
It’s the ultimate source of truth for getting onboarded to any product, library, or framework. When you can get the truth directly and free from the source, why would—and should—you trust anything else?
Remember those earlier tweets and blog posts 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: discussing 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 inherently 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, a niche topic, or an unfamiliar concept, 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, yes, you’re better off starting with the documentation. If you get the wrong info there, you can reach out to the product creators, file a bug report, and hold someone accountable. But who are you going to hold accountable when Gemini hallucinates a command that doesn’t exist, or never will?
Embrace the Cheat Code
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 (if you’re printing things out for some reason), and your precious 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, learn effectively, and keep your sanity intact. Then, yeah, go read it. Your future self will thank you.
