I've always been a fan of having documentation living alongside the code:

• Version control: just like code, doc evolve. Why use a different system when you're already using a VCS like git? Especially when you have multiple people evolving the docs at the same time, with potentially conflicting changes.
• Proximity: the rg or grep will yield code and documentation results, making it much easier to keep it up to date.
• Formal approval: for those following documentation-driven development, starting with a review of the proposed change in the form of documentation change help understand the final product/API. This is different from active collaboration - for those, Google Docs still provides a superior UX.
• Automatic generation: when using a different system for hosting the docs (Google Docs, Confluence, Notion, etc.), it's quite laborious to copy-paste APIs and example code. Wouldn't it better if you could automatically reference those interfaces by generating their documentation (e.g., with sphinx for Python, jsdoc, etc.)?
• Testing: static code examples in documentation are a good start, but it's even better when they're tested, which you can do when running code examples in docs is part of your continuous integration process. See Python's doctest for example. In a way, the documentation is the spec.
• Efficient editing: you benefit from all your text editor tools, and can script mass-changes.

We will be spending more time writing docs

First observation: AI agents have considerably increased the proportion of markdown files in commits. That's usually because folks check out the agent's implementation, which is a very good idea. It's also because you save a lot agentic iteration time when you write rules files (.mdc files) to guide agents' execution. So, whether or not you agree with the thesis, it is happening.

I would submit that 80% of the rules file could have been documentation instead, or potentially are already documented elsewhere. Just like code should be primarily written for humans to read, all files in a repository is written primarily for humans to read and review. This also applies to rules files created to guide agentic execution.

This is also consistent with engineers shifting their focus left. The history of engineering tooling is an history of higher and higher level abstractions, from machine code to C, to dynamic languages, to SDK, and now to not even writing code and only focusing on the spec, and guidelines. Just like we don't review the machine code produced by the compiler, there might be a day where we don't review the code generated by an LLM provided it respects the specs and the guidelines (security will be a key concern there). In that world, we'll spend most of our energy reviewing those docs. Conclusion: those docs need to be written first and foremost for humans review.

Why AI makes it even more meaningful to move docs into your repo

You could use MCP and other approaches (skills) to give access to your documentation. But the same arguments I laid out in the beginning still apply, especially the version control piece. Most documentation system are not design for fast iteration with strong concurrency control.

AI agents also solve the long standing problem about keeping docs up-to-date. A common objection to writing docs is: "why bother? read the code - docs are always up to date". (the same line of arguments would apply to brushing your teeth). AI agents solve this problem. They take away the laborious work to ensure code & documentation alignment. Quite game-changing.

AI agents benefit from higher level context. Moving your docs (including, perhaps, your architecture proposals - RFCs, your product specs - PRDs, etc.) will provide that extra context.

Materialized plans with learnings will save token & iteration time. Imagine researching "the best way to do X" in a massive codebase. You will spend a lot of tokens finding the answer to that question. Documenting the answer to that question and materializing it in the repository will enable your colleague to skip that research step later (and keep it up-to-date with extra learnings, best practices, etc.!).

Answer to objections

Waiting for a code review for docs will deter from updating docs. (1) What if you weren't the one writing those docs? (2) Who says all repo content change need to go through review? (3) As we shift more and more left, won't the documentation change or implementation plan be the most important thing to review?

AI agents write long, convoluted docs. Just like code, (1) review the agent's work, (2) fix the agent's work, and (3) write your own docs (like this article: none of this content has been generated by AI!)

[your_preferred_tool] is better at [tables/schemas/links]. AI is getting incredibly good at generating mermaid schemas (supported by Github), tables, etc.

[your_preferred_tool] is better for human collaboration. Yes, Google Docs is still much better for active collaboration, so it's fair to continue using it for that use case. But once the documentation is in a good place, I would move it in the repo (Google Docs has a nifty "Copy as Markdown" feature that I use all the time).

References and articles

As always, there are more resources on my repo charlax/professional-programming

• Specifications Are Becoming the Real Source Code
• Getting AI to Work in Complex Codebases
• Documentation-Driven Development
• Writing automated tests for your documentation
• 🏙 Documentation is king, Kenneth Reitz
• The documentation system
• Write documentation first. Then build.
• Diátaxis: a systematic approach to technical documentation authoring: tutorials, how-to guides, technical reference, and explanation.

The palest ink is more reliable than the most powerful memory. -- Chinese proverb