My belief is that documentation belongs in markdown files, in the repository, next to the code it describes. Not in a wiki, not in a knowledge base, not in a vector store. This is a live argument in AI engineering right now, and I want to be clear about where I stand before you hire me.
The short version
Documentation that lives anywhere other than the repository goes stale. Not sometimes — reliably, and fast.
The reason is mechanical rather than cultural. When docs live in a separate system, updating them is a second task, in a second tool, with a second login, that no code review enforces and no test catches. Skipping it costs nothing today. So it gets skipped, and six months later the wiki describes a system that no longer exists, and the honest advice to a new engineer is "don't trust the docs, read the code."
When documentation sits in the repo, changing it is part of the change. It appears in the diff. A reviewer sees the code and the description of the code in the same pull request, and the mismatch between them is visible in the one place engineers are already looking.
What markdown in the repo gets you
- It's diffable. You can see what changed about the explanation, not just the code — and when. "Why does this do that?" is often answered by the commit that changed the paragraph, not the one that changed the function.
- It's reviewable. Documentation goes through the same pull request as the code. Wrong docs get caught the same way wrong code does.
- It versions with the thing it describes. Check out a tag from eighteen months ago and the documentation you get is the documentation for that version. A wiki has exactly one version: now, more or less.
- It's portable. Plain text survives your team leaving, your vendor being acquired, and your tooling being replaced. Nothing has to be exported from anything.
- It's already where the work happens. No context switch, no separate permissions model, no second place to search.
- Agents read it natively. Coding agents are extremely good at listing directories, grepping, and reading files. A
README.mdbeside a module is retrievable without infrastructure — no index to build, no embedding to refresh, no sync job to fail quietly.
That last point is why this debate got loud. The same properties that made files good for humans turned out to make them good for models, and a lot of teams who built retrieval infrastructure discovered their agents worked better pointed at plain files.
Where the other side is right
I don't think this is a universal law, and it's worth being precise about the limits.
Search at scale is a real problem. Grep degrades on paraphrase and synonym. Once a corpus is large enough that people can't find what they need by knowing roughly where it lives, semantic retrieval genuinely beats keyword matching. That's an argument for indexing your files — not for moving them somewhere else.
Concurrency and shared state need real guarantees. If many writers or many agents are updating the same content simultaneously, files will corrupt in ways a database won't. Documentation in a repo mostly avoids this, because git is the concurrency control — but it's a real constraint in other contexts.
Some documentation genuinely isn't about the code. Runbooks spanning multiple services, compliance evidence, customer-facing manuals, and organizational process don't have an obvious repository to live beside. Forcing them into one is worse than putting them where they belong.
The honest position isn't "files always win." It's that files should be the default, and heavier infrastructure should be added when something specific forces it — not chosen at the start because it looks more serious.
What this means for your project
If you hire me, this is what happens by default:
- Architecture and decisions in the repo. A
docs/directory or markdown beside the module, in the same pull requests as the code. - Decision records for the non-obvious choices. Short files capturing what was decided, what the alternatives were, and why — because the reasoning is what disappears first, and it's what someone will need in two years.
CLAUDE.mdor equivalent, when agents are in the loop. If your team uses coding agents, the conventions and context they need are a file in the repo, versioned with everything else.- Generated where generation is honest. API references from the schema, not hand-maintained in parallel with it. Documentation that can be derived should be derived.
If your organization already has a documentation platform, I'll work within it — this is a default, not an ultimatum. But I'll tell you what it costs, and in my experience the cost is that the docs are wrong within a year.
Why I'm telling you this
Documentation quality is one of the few things that determines whether you can fire your consultant. A system nobody but its author understands is a system you're stuck paying for.
I'd rather build the other kind. The point of writing it down properly is that my continued involvement stays optional.
Questions
If you disagree with any of this, I'd genuinely like to hear it — the argument is better than the conclusion.