README.md is where code goes to die

A repository with 5,000 stars and a three-year-old README.md isn’t a success story. It’s a liability.

We’ve all seen it. You find the perfect library, check the GitHub stars, and see a vibrant commit history. Then you try to run npm install and the build fails because the instructions refer to a version of Node that hasn't been supported since the Obama administration.

Documentation in open source isn't just bad. It’s fundamentally broken by design.

The Engineering Obsession with Code

Engineers like logic and compilers. We like things that go green or red. Documentation is neither.

When we write code, the feedback loop is instantaneous. You break a type definition, the LSP screams at you. You write a bad test, the CI pipeline fails.

Writing documentation feels like screaming into a void. There is no linter for context. There is no compiler for clarity.

Most devs treat documentation as a chore to be completed after the "real work" is done. If you spend 40 hours on a feature, you’ll spend 15 minutes on the docs/ folder. This is why your CONTRIBUTING.md is usually a lie.

The Half-Life of a Doc

The moment you hit git push, your documentation starts decaying. It has a shorter half-life than the code it describes.

API endpoints change. Variable names get refactored. Dependencies get bumped. But the human-readable explanation of why we chose that specific architectural pattern stays static.

Eventually, the delta between what the code does and what the docs say becomes so large that the docs become dangerous. In a production environment, wrong documentation is worse than no documentation.

If there’s no file, I’ll read the source code. If the file tells me to run scripts/setup.sh and that script was deleted six months ago, I’ve just wasted twenty minutes on a ghost.

The Cost of the 'Just Read the Source' Fallacy

Senior engineers love to say, "The code is the documentation." This is arrogant and wrong.

Code tells you how. It never tells you why.

When a new hire joins your team, they spend the first three weeks playing archeologist. They aren't learning your business logic; they’re trying to figure out why InternalHelperFactoryV2 exists and if it’s safe to delete it.

We did some internal analysis at git11. Engineers spend roughly 30% of their day just trying to understand existing context. In a team of ten, you’re effectively paying three people a full salary just to be confused.

Markdown is a Primitive Tool

We are using 20th-century tools for 21st-century complexity. Managing documentation through static .md files is like managing a database with a spreadsheet.

Markdown is great for formatting, but it lacks relational integrity. If I change a function signature in src/auth.ts, my docs/authentication.md doesn't know.

We need tools that bridge the gap between AST (Abstract Syntax Tree) and prose. Documentation should be treated as a first-class citizen in the build pipeline. If the docs don't match the exported types, the build should fail. Period.

The Maintenance Burden

Open source maintainers are tired. Most of them are doing this for free after their day jobs.

Asking a solo dev to maintain a comprehensive documentation site is asking for burnout. They want to solve interesting problems, not explain for the thousandth time how to set up an environment variable in Windows.

This is where AI actually matters. Not for writing the code, but for maintaining the metadata around the code. AI is better than humans at the tedious task of tracking changes across 500 files and updating a summary.

Stop Writing 'How-To' Guides

Most repositories fail because they focus on 'How-To' instead of 'What Is'.

Tutorials are easy to write and even easier to break. They are fragile.

What your repo actually needs is a high-level conceptual map. If I understand the data flow, I can figure out the syntax. If you give me the syntax but no map, I'm lost the moment I hit a bug.

What We Are Building

At git11, we’re obsessed with the gap between what's in the repo and what's in your head.

We don't want to help you write more files. We want to eliminate the need for manual documentation updates entirely. If the code changes, the context should update automatically.

Documentation shouldn't be a separate task. It should be an artifact of the development process, as reliable as a compiled binary.

Throw away your pride. Admit your docs are garbage. Then, stop trying to fix them by hand.