Documentation is where code goes to die

Most startups documentation efforts are a waste of CPU cycles.

You have a Confluence space that hasn't been touched since the Series A. You have a README.md that still explains how to install a version of Node that hit end-of-life in 2021.

We pretend we care about documentation. We don’t. We care about shipping features, and we treat writing about code as a tax we’re constantly trying to evade.

The Freshness Trap

The biggest mistake startups make is believing documentation is a static asset. It isn't. It’s a depreciating one.

The moment you merge a PR, your existing docs lose value. If you aren't updating them in the same commit, you’re creating tech debt.

We see teams spend two weeks writing a "Master Architecture Guide." By the time the PDF is exported, the auth-service has been refactored and the diagram is a lie.

Stop writing long-form prose. Nobody reads it. Write small, atomic notes that live next to the code. If it’s not in the repo, it doesn't exist.

READMEs are for humans, not mirrors

Your README shouldn't list every file in the directory. ls already does that.

A README has one job: get a dev from git clone to a running local environment in under five minutes. If your setup involves fifteen manual steps and a "ping Sarah for the .env file," you’ve failed.

We see READMEs filled with "High-level Vision Statements." Delete them. Tell me how to run the tests. Tell me which microservices I need to mock.

If a human can figure it out by looking at the package.json or go.mod, don't write it down. Logic duplication is just as bad in docs as it is in code.

The "Obvious Code" Fallacy

There’s a specific brand of arrogance among senior engineers: the belief that "good code documents itself."

This is wrong. Good code tells you what is happening. It never tells you why.

if (user.status === 4) { ... } might be clear to the person who wrote the legacy billing engine. To the new hire, it’s a magic number from hell.

Your code cannot explain the business constraint that forced a hack three years ago. It cannot explain why you chose a B-Tree over a Hash Map for that specific edge case.

Use comments for the "Why." Save the "What" for the function names.

Tooling won't save a broken culture

Startups love buying tools to solve social problems. You buy a fancy Notion template or a shiny AI-doc generator. It doesn't work.

Documentation fails because it isn't part of the Definition of Done. If a PR is approved without updated docs, your team is saying that documentation is optional.

We’ve found that the best teams treat docs/ like src/. They lint it. They review it. They break the build if it’s missing.

At git11, we’ve analyzed thousands of repos. The ones with the lowest churn aren't the ones with the most docs. They're the ones where the docs are actually accurate.

The Architecture Decision Record (ADR)

If you want to actually fix this, start using ADRs. Use a simple tool like adr-tools or just a folder called docs/adr.

An ADR is a short markdown file: 0004-use-postgres-for-events.md. It lists the context, the decision, and the consequences.

It’s immutable. You don't update an ADR; you write a new one that supersedes the old one.

This creates an audit trail of your technical evolution. When a new dev asks, "Why are we using a graph database for a simple blog?", you point them to the ADR from 2022.

AI is the only way out

Manually maintaining docs is a losing game. Humans are too inconsistent and too busy.

This is why we’re building tools to automate the context gathering. If an AI can watch your PRs, it can update the README. If it can see your schema changes, it can update the ERD.

But even AI needs a baseline. It needs you to stop writing garbage and start caring about the "Why."

Documentation isn't an act of kindness for the next engineer. It’s an act of survival for your future self who will forget why this code exists in six months.

Stop writing manifestos. Start writing docs/ADR-001.md. Check it into main. Move on.