No, I'm not arguing you should rebuild Mintlify (or any other documentation hosting platform).
These tools are very good at what they are designed to do. They help teams publish, organize, and maintain human-readable documentation with minimal friction. For most products, that is exactly the right abstraction.
This article is about a different problem.
Once documentation starts being consumed by AI systems at runtime, it stops being just an external explanation layer. It becomes part of the system's operational context. At that point, the usual assumptions around documentation break down.
Documentation was never meant to be part of the runtime
Traditionally, documentation sits clearly outside the system.
Code executes.
Documentation explains.
Humans read.
Machines do not.
That separation held as long as software behavior was determined at compile time and explanations were written after the fact. But it becomes unstable once systems begin to reason, generate explanations, or adapt dynamically using language.
Many AI systems today rely on prompts, retrieved context, or more generally natural language inputs that shape behavior at runtime. That information has to come from somewhere. In practice, it often originates in documentation, even if indirectly.
The problem is not that this happens. The problem is that documentation was not designed for this role.
Drift
When documentation is reused as system input, a familiar failure mode appears: drift.
- Definitions change in docs, but prompts quietly fork.
- Similar concepts get re-expressed slightly differently across many prompts.
Over time, this turns into an unmanageable prompt zoo.
Prompts do not need to be documented (publicly). That is not the issue, and leaving them undocumented is often intentional (for example to protect intellectual property).
The issue is that without a shared, runtime-available set of definitions and concepts, every prompt ends up re-encoding the same ideas in slightly different ways. Keeping documentation aligned and available at runtime allows prompts to reference a common semantic substrate instead of duplicating it.
And that’s where the idea of runtime-coupled documentation comes from.
Just to be clear, publishing documentation does not mean exposing internal control logic. Documentation defines shared concepts and boundaries so users and systems speak the same language. Prompts encode internal steering and implementation choices. Those two surfaces overlap in language, but they serve different purposes and do not need to be exposed in the same way.
What "runtime-coupled" actually means
Runtime-coupled documentation is not documentation that happens to be indexed or searchable.
It has a few specific properties:
-
Fine-grained addressability. Definitions, sections, examples, and constraints are identifiable and referenceable as units.
-
Availability in the inference path. The system can consult documentation while generating outputs, not only during offline preprocessing.
-
Semantic structure. The structure reflects concepts and relationships, not pages and layout.
-
Versioning and traceability. You can determine which version of which definition influenced a given output.
Once documentation satisfies these properties, it is no longer just explanatory content. It becomes part of the system’s runtime state.
Why this is not about replacing documentation platforms
This is not a critique of Mintlify or similar tools.
Documentation platforms are optimized for human readers. They model documentation as pages, navigation trees, and rendered content. That is the correct abstraction for their primary use case.
Even when APIs exist, the underlying model remains presentation-first. Concepts are implicit. Semantics are inferred, not explicit.
You can scrape, chunk, or embed this content, and for many applications that is sufficient. But that is not the same as runtime coupling. It is a best-effort approximation layered on top of tools that were never designed for this role.
A parallel from AI tooling
A similar argument appears in Lee Robinson's discussion of AI agents and content systems.
Lee argues for building his own CMS. Not because CMSs are bad, but because traditional CMS abstractions introduce friction once AI coding agents are part of the workflow. In that setting, content hidden behind APIs, schemas, and publishing pipelines becomes harder for both humans and AI to modify cheaply and reliably.
His point is not "everyone should build their own CMS". It is that once AI systems actively produce and consume content, certain abstractions stop helping.
The same pattern shows up with documentation used at runtime.
On-prem makes the boundary unavoidable
Now add one more constraint: on-prem deployment.
In regulated or sensitive environments, systems often must run with:
- no outbound network access,
- strict audit requirements,
- full control over everything that influences behavior.
If an AI system depends on documentation that lives outside the deployment boundary, then the deployed system is incomplete.
You cannot guarantee availability.
You cannot guarantee consistency.
You cannot reliably audit what knowledge was consulted.
At that point, documentation is no longer "just content". It is part of the trusted system surface. And anything in that category must be owned, versioned, and deployable with the system.
What this means in practice
Once documentation is:
- consulted by AI systems at runtime,
- required for correct behavior or explanation,
- expected to work in on-prem or regulated environments,
it must be in-sourced.
Not to replace documentation platforms.
Not to rebuild existing tools.
But because documentation has crossed a boundary.
It has moved from external reference to internal dependency.
A subtle shift in how we think about docs
This is ultimately a mental model shift.
Documentation is no longer only something that explains the system from the outside, for humans to read. In AI-driven systems, it increasingly participates in how the system understands itself.
As soon as documentation enters the inference loop, it stops being purely editorial. It becomes part of the runtime.
And once that happens, architectural constraints, not tooling preference, determine where it must live.