The Documentation is the Code
A great inversion in software development
I’ve been working on a project that attempts to standardize an aspect of developing agentic systems. This article isn’t about that project, but some of the feedback I’ve received as I’ve exposed the project to the world. Specifically, feedback that has the following flavor:
It’s just markdown files. Real *AI related thing* is actual, running code
I’d like to take a moment to unpack what this sentiment implies, the context in which it exists, and how it relates to where software development is going as a discipline.
The Fight Between Documentation and Code
Software developers have been hating creating documentation since software has been a thing. In my article on agile project management I discuss, among many things, the “Agile Manifesto”. This document started the agile software development mentality that dominates modern software development. Its second tenant is to prioritize functional software over documentation.
Software is an evolving and dynamic thing. Over several revisions a project can drastically change, meaning documentation around that software has to be updated and maintained constantly to keep up with changes in the codebase. This puts a strain on those maintaining the codebase; do they prioritize their time maintaining documentation that will inevitably be made antiquated or focus on working on the code that actually drives the project forward?
The balance between these two things is a contentious debate, and the correct approach depends on your role, the project you’re working on, the size of the team you’re working in, and the dynamics of that team.
If you’re a solo founder cranking away at a new product, you don’t have time to document every function, every interface, and every API. You have bigger fish to fry, and the documentation is superfluous because you, the solo founder, are the only person who would be looking at the code anyway.
For a small size team of experienced developers, some documentation is important, but chiefly in coordinating high-level initiatives and aligning the team in the right direction. Schematics, specs for key APIs where two developers are working on opposite ends simultaneously, and tickets to keep the team aligned towards the same goal is pretty much all you need.
As a project grows, things become more complicated. Developers might join and leave the company, marketing teams might need information about specific aspects of how the product functions, and you might need to bring on a technical support team to assist customers. Quickly, “ask the guy who built it” becomes infeasible if not impossible. At this point, weather the technical team likes it or not, they’re going to have to sit down and write some docs.
And this is the way it’s gone, more or less, for over 40 years. Different developers might have different opinions as to when you start writing docs, how much you write, and why, but generally documentation gets written out of necessity as a project matures. With AI, this status quo completely changes.
The Changing Landscape of Software Development
Agentic systems are already outpacing human development. Is the code quality good? Not always, but it seems like it’s starting to be good enough, especially when guided by a competent developer.
The paradigm of a single person sitting down over the course of months and fleshing out a prototype by hand, frankly, is the past. The modern paradigm of software development is people who know what they’re doing delegating their understanding to AI systems and making sure those AI systems are implementing robust solutions that are faithful to their vision.
In essence, the role of software developer is becoming more like the role of technical product owner/project manager. Doing a good job in complex environments still requires the hard skills of software development; you need to know what you’re doing to manage a team of AI agents effectively, but sitting down and writing individual lines of code is becoming a rarity.
With the fundamental bedrock of software development changing so significantly, it’s no surprise that the role of documentation is changing along with it.
AI, and the Role of Documentation
Every software project is now a small to mid-sized team. Every developer is using AI to augment their work. Soon, most knowledge workers will be in the same situation. As AI grows and evolves, most humans will be augmented, assisted, and supported by AI systems in some way. I’m both excited and afraid about the prospect, like most people are. Regardless of one’s feelings, though, it’s the obvious reality.
When we look to software development, specifically, I feel there’s a cognitive dissonance between the work people do, vs the work they imagine that they do. Many developers have been writing code for decades, and they still imagine themselves as writing code. They use AI to assist them to be faster, but they’re ultimately the ones creating it. However, as AI begins to generate 50%, 60%, 90%, 99% of a codebase, this conceptualization becomes less and less accurate. More and more, saying you “wrote the code” on a project you worked on with an AI system feels more like a quirk of language than a truthful statement.
Developers who have spent their careers writing code now, in plain truth, don’t. They’re still getting something done, but they don’t know how to describe what they’re doing and why they’re necessary. I feel like some developers have yet to make the leap in terms of how they conceptualize themselves. In reality they are a manager, not a developer. A manager that’s managing very fast, fairly competent, but oddly inconsistent AI developers. They can understand large amounts of information quickly, and leverage that information to write a significant amount of code rapidly, but also ignore entire critical pieces of documentation, make odd assumptions that are clearly out of alignment with the subtext of the project they’re working on, and completely reset their understanding of a problem every time you close and open a terminal.
In this environment, documentation is not some superfluous line item; it is fundamental and absolutely critical to being an effective developer in the modern era. Naturally, as LLMs remain inconsistent, strong software development skills remain fundamentally important. As LLMs and agentic systems continue to evolve, though, the instructions used to get agentic systems to understand a codebase and make changes begin to become a more important fundamental artifact than the code itself. Increasingly, code is made based on documentation, rather than the other way around.
Thus, we go back to the sentiment that inspired this article
It’s just markdown files. Real *AI related thing* is actual, running code
I see this sentiment a lot throughout the internet: that agentic systems are complex and sophisticated pieces of software, and the various prompts and context that guide them are of marginal interest. There’s some wisdom in it; it seems like every day someone posts an article about how they “made an AI agent to help them make a billion dollars online,” and that “AI agent” is Claude, pointed to three poorly worded markdown files. At this point, “a bunch of markdown files.” is indicative of hoaky, hacky, and hypy software, and the frequency and cheapness of this form of content have a natural erosive quality to the idea of structuring information for agentic systems, which already inherited a bad flavor from its father, “prompt engineering.”
While true and justified in a dimension, there’s also a significant untruth in the statement as well. That the structuring of information such that it can be easily accessed and understood by an agent is not of importance. As agentic systems evolve, and skills, instructions, MCP servers, and other paradigms become bundled into larger and larger projects, the efficient organization of information becomes a critical and not-so-trivial task.
I worry that some developers don’t understand that documentation is increasingly shifting from a byproduct of software to becoming its fundamental artifact. Defining systems, how they work, and the intent behind them is of critical importance to the modern AI-augmented developer. Defining that information in a consistent manner that agentic systems can continually reference over the lifetime of a project is becoming a fundamental skill. Thus, the ability to write and maintain good documentation (perhaps more so than writing good code) is becoming a fundamentally important skill.
The Agent Harnesses Standard
The ideas in this article are why I’m writing the Agent Harnesses Standard, the goal of which is to define how information can be structured such that it can be more robustly leveraged by agentic systems. For it to be successful, I can’t build it alone. It’s the type of thing that requires a diversity of opinions to flesh out correctly. If you’re interested in this topic, check out the github for information on contributing.
The inversion is real, but it surfaces an organizational problem most teams haven't solved: documentation has no clear owner. It falls between engineering, product, and whoever handles developer relations, and everyone assumes someone else is keeping it current. If docs become the authoritative source of intent for agents, that ownership gap becomes a production risk, not just a hygiene issue.
You might want to check out Manny Silva's Docs as Tests and AI ... seems like that's where you are heading.
https://www.isophist.com/p/every-doc-makes-a-promise