Documentation has a new reader

I was cautious about flooding a code repository with documentation. There should be documentation close to the code, but in a limited and intentional form. A README with context about the application, a high-level architectural overview, and clear setup instructions to get a development environment running. Some teams add ADRs and keep those near the code as well. Everything else lives in a more dedicated space like Notion or Confluence.

That separation made sense. Code stays lean, documentation stays organised elsewhere, and everyone knows where to look.

With Claude Code, keeping documentation inside the repository makes a lot more sense. It gives AI direct access to the full system context without having to bridge gaps via MCPs or external tools. It’s simpler, and it removes friction.

AI is very effective at contributing to documentation. What it generates can be extensive, but that’s no longer a drawback. You don’t have to read everything. You can ask it to summarise, extract decisions, or explain specific parts of the system. By moving documentation closer to the code, you effectively gain a team member who never gets tired of writing or updating docs and who has a reliable memory of past decisions and how the system is supposed to work.

Documentation stops being something you maintain only for humans. It becomes part of how the system itself is understood.