There is a famous phenomenon among engineering teams where someone writes beautiful detailed meticulously structured documentation. It lives in the docs folder next to the code. Nobody reads it. Not because readers are lazy or unmotivated - they genuinely intend to read it when they get started - but because the act of reading documentation feels like homework and checking a real implementation feels like discovery. The documents end up two weeks behind whatever shipped yesterday, full of examples for features that no longer exist, written in a tone that sounds like it was translated through three people. And then someone else writes a project with terrible docs. Maybe one sentence on the README. A paragraph that assumes you already know what the thing does. Three hours of debugging later they submit their first pull request, and they read the actual source code to figure out what is going wrong. The code turns out to be beautiful. They learn something about how it works not by reading a guide but by following a single call chain from entry point through three abstraction layers to where the real logic lives.

I noticed this pattern early in my career working on an internal tool that was documented by three paragraphs and a link to an external service. That tool became one of the most polished pieces of software our team shipped. Not because we planned for polish - it emerged from the fact that nobody could open an issue describing what was wrong without reading through roughly two hundred lines of code first. By the time someone understood enough to file a report, they already knew enough to fix it themselves. The documentation was bad by every conventional metric: incomplete outdated almost useless. Yet the project had higher code quality more engaged contributors and fewer critical bugs than anything else on our team’s portfolio that year. Documentation was not the reason for this success but something about how bad docs forced a different reading pattern turned out to help.

Modern software development treats documentation as an entry requirement. Write your README before merging. Add docstrings to every public function. Keep the CONTRIBUTING guide accurate and up to date. This discipline produces clean documentation repositories that nobody reads while simultaneously creating an illusion of quality that lets teams ship faster in the short term. The trap is that good docs substitute for understanding rather than supplementing it. When someone encounters a bug and the docs cover their exact use case the natural reaction is to follow the documented pattern one more time instead of looking at the code. They spend twenty minutes trying four different approaches from documentation examples, three of which are mutually inconsistent, before finally deciding that reading the actual implementation is faster than reading another blog post about the API. If those docs had been less precise the bug would have been found sooner.

This is not an argument for laziness or negligence. I am not suggesting projects should omit their documentation entirely or write deliberately vague guides. What I am interested in is the space between exhaustive and absent, where the code speaks slightly louder than any description of it. A half-finished README with a single example that actually works. A config file with comments explaining why certain defaults exist. A test suite that reads like documentation for someone willing to look at it. These are not better or worse than good docs in any conventional sense. They create an environment where reading code is easier than reading text because the text alone cannot explain what you need, and the code actually can. The contributor who takes this detour through the source code often ends up understanding the system better than someone who read thirty pages of explanation, partly because they were forced to build their own mental model rather than borrowing someone else’s.

The paradox has a name in organizational psychology called productive friction - situations where making something slightly harder to do for the first time makes it significantly easier to do well afterward. The cost of bad documentation is higher onboarding during the first day. The benefit is that every contributor who pushes past that barrier actually understands what they are contributing and why. A tutorial teaches you how to use the tool. Reading broken code teaches you how something works. The distinction matters most for anyone who wants to go beyond surface-level usage, which is probably most people reading this. If your goal is only to integrate quickly once and never touch the thing again, great documentation saves time. If your goal is to ship reliable work on a codebase that will live longer than your involvement in it, sometimes worse docs are the friend you do not know you needed.