You know the drill: launch a new tool, be happy for 5 minutes, then sit down to write a 50-page README dissertation to explain how it works.
I'm sorry, but nobody's reading all that. At best, they're skimming the first few lines, copy-pasting your installation command, and guessing their way through the rest. If they hit a wall, they might ask ChatGPT to sum it up for them.
The really old schoole ones are immediately opening an issue to ask a question that's answered on page 17 of your beautifully crafted docs.
It's not that documentation isn't valuable — it is. But the obsession with exhaustive, encyclopedic documentation often masks a deeper issue: your tool is too complicated. If your software requires a manual thicker than the average novel, maybe the problem isn't with the users. Maybe it's with the UX of your software itself.
Good Software Explains Itself
The best software is intuitive. You open it up, and it just makes sense. You don't need to consult a tutorial or spend a weekend reading markdown files. The interface guides you. The API feels natural. The defaults are smart. The learning curve is gentle.
Think about tools like curl, htop, or even git (despite its flaws). These tools have quirks, sure—but they're discoverable. You don't need to read a 50-step guide to get started. You just start using them.
If your users need a 10-minute explainer video before they can run a "hello world," your tool is not friendly. It's a puzzle — and most developers don't have time to solve it.
Documentation as a Crutch
Over-documentation is often a symptom of bad developer experience. It's what happens when you ship an awkward interface and then try to explain it away with a wall of text. But here's the thing: nobody wants to read your excuses. They want something that works, feels good, and doesn't make them feel stupid.
It's the same reason nobody reads the manual for a microwave. They expect to press a button and get a result. If you need a tutorial to reheat your pizza, the microwave sucks. Same goes for your CLI tool.
Don't Hide Behind Docs — Fix the UX
Before you write a single line of documentation, ask yourself:
- Could this be simpler?
- Is the API self-explanatory?
- Can the user see what's going on without reading anything?
- Are the defaults smart enough?
If the answer to those is "no," don't reach for a README — fix the product. Your docs are not a substitute for thoughtful design.
That means:
- Make the
--helpoutput actually helpful. - Provide real-world examples in the CLI output itself.
- Use meaningful error messages.
- Reduce configuration wherever possible.
Every improvement here is worth more than another paragraph in your docs.
Make Docs the Backup, Not the Frontline
Documentation should be there for when things get tricky — not as the main interface to your tool. It's the supporting actor, not the star of the show.
Good documentation is:
- Concise
- Example-driven
- Searchable
- Focused on use, not theory
If your doc site looks like a programming textbook, you've gone too far. If you're explaining your internal architecture before someone knows how to run your tool, you've already lost them.
Don't Build for Readers, Build for Users
Developers are busy. They don't want to read — they want to build. So write less documentation and more intuitive code. Make your tool feel obvious. Make it rewarding to explore. Treat your first-time user like they just want to try something quickly, not like they're signing up for a four-week course.
Documentation isn't bad. But if it's the only way people can understand your tool, it means your design failed.
So next time you're about to dive into writing a 20-page usage guide, stop. Look at your software. Ask if you can make it better instead of just explaining it harder.
Because nobody wants to read your docs. And honestly? They shouldn't have to.