Documentation is a Debt You Can’t Refinance

The average README is a lie.

It’s written in a moment of peak optimism—usually right after the first green build—and then never touched again. By the time you’re three months into a project, that npm install instruction is probably missing a peer dependency, and the architecture diagram is a relic of a design session that was discarded in an 11:00 PM refactor.

Most open-source projects don't have a documentation problem. They have a reality problem. We treat docs like a secondary artifact, something to be 'polished' later, when we should treat them like a failing test case.

The README Lie

Search any mid-tier GitHub repo. You’ll find a README.md that spends 400 words explaining how to install a package but zero words explaining why the project exists or how the src/internal/scheduler.ts actually handles race conditions.

We focus on the onboarding ritual because it’s easy. It’s rote. Explaining the logic behind a complex state machine is hard. It requires cognitive load that most engineers would rather spend on the next feature.

This is why 90% of repositories are functionally opaque. If I have to read your package.json, four levels of nested directories, and a dozen .ts files just to understand your entry point, your documentation has failed.

Tribal Knowledge is a Performance Killer

In most shops, the real documentation isn't in Git. It’s in Slack threads, private DMs, and the brain of that one engineer who’s been there since the seed round.

When that engineer leaves or goes on vacation, velocity drops to zero. We call this the 'Bus Factor,' but it’s actually a failure of engineering discipline. We’re trading long-term project health for the short-term dopamine hit of merging a PR.

Every time a new hire asks "where is the logic for the billing webhook?" in Slack, you’ve failed. That question is a bug report for your docs. If the answer isn't a link to a file or a clear doc site, you are burning money on developer frustration.

The Maintenance Burden is the Point

Engineers complain that docs go out of date. Good. If your code changes so fast that writing it down feels impossible, your architecture is likely too volatile.

Documentation is the friction that forces you to think about whether a change is actually necessary. When you have to update the CONTRACT.md or the API spec, you realize how much complexity you’re adding.

Without that friction, we just keep layering abstractions until the system is a mess. Documentation isn't a chore; it’s the only way to prove you actually understand what you just built.

Tools Won't Save You (Usually)

We’ve tried everything. JSDoc is a graveyard of unused tags. Swagger is okay, but only if you actually keep the annotations accurate. Most auto-generated docs are just a list of function names that you could have seen in your IDE anyway.

GetUserData(id: string) doesn’t need a docstring that says "Gets user data by ID." It needs a note explaining that it hits a cached Redis layer before falling back to Postgres and that it throws a 404 if the user is soft-deleted.

We’re building tools at git11 to bridge this gap, but tools are only as good as the intent behind them. An AI can summarize your code, but it can't tell your team why you chose a NoSQL database over a relational one in 2022.

The Cost of Silence

What does this cost? Real numbers. A senior engineer spends roughly 30% of their day just trying to understand existing code before they write a single line.

In a team of 10, that’s 3 people’s worth of salary spent on archaeological digs through your own git history. If you’re paying $180k per head, you’re losing over half a million dollars a year to poor documentation.

It’s not just a 'nicety.' It’s a line item on your P&L.

Fix the Culture, Then the Markdown

Stop accepting PRs that don't include doc updates. If the logic changed, the docs must change. No exceptions.

Make it part of your CI/CD. If your docs/ folder hasn't been touched in a PR that modifies src/, trigger a warning. It’s not about being pedantic; it’s about survival.

Documentation is code. Treat it with the same level of paranoia you bring to your production database migrations.

Stop writing for the 'user' and start writing for the engineer who has to debug your mess at 2:00 AM. Usually, that person is you.