Maybe DRY is the wrong optimization for agent-facing documentation. We reduced duplication to make documentation easier to maintain, but in doing so, we moved the work of assembling it to the reader.
Imagine that authentication works the same way across twenty workflows. Copy its instructions into every workflow, and the next change needs to be made in twenty places. Instead, we put the instructions in one place and link to them. One source of truth, easier maintenance.
That trade-off made sense when people wrote and maintained documentation. Increasingly though, agents don’t just consume documentation. They help maintain it too, and that changes the economics of it. Maybe documentation should remain normalized for maintenance while becoming denormalized for consumption.
DRY moved work to the reader
Consider a tutorial for deploying an API. It tells you to configure authentication, create the service, assign permissions, then deploy it. Each step points somewhere else.
Need to configure authentication? See the authentication documentation. Need the right permissions? See the permissions reference. Deployment has its own guide, of course.
We’ve removed duplication, but we haven’t removed work. The reader still needs to follow each link and find the relevant section. Then they have to understand it in the context of the original task and assemble the fragments into a complete workflow.
Agents do the same work, except every hop requires another retrieval or tool call. The agent decides what to retrieve, interprets the result, keeps the relevant part in context, then returns to the original task. When the documentation doesn’t provide everything it needs, it may search the web or retrieve older guidance.
Each extra source creates another opportunity for conflicting information. Normalization makes documentation cheaper to maintain, and keep consistent, but it also makes it more expensive to consume.
Put the whole workflow in one resource
Put everything on one page sounds like terrible documentation advice. So let me qualify it.
Don’t put everything there is to know about a service on one enormous page. Put everything necessary to complete a workflow in one resource.
If an agent needs to deploy an API, it shouldn’t have to retrieve five resources to discover how authentication and permissions fit with deployment. Give it the complete deployment workflow. Some of that information will also exist elsewhere, and that’s the point. The unit we’re optimizing is no longer a unique piece of information. It’s the workflow.
Progressive disclosure still matters. We don’t want to fill an agent’s context with information it doesn’t need. But progressive disclosure should help an agent choose the right context, not force it to assemble that context itself. A skill supporting ten workflows doesn’t need to load all ten. It can identify the relevant workflow and load one resource containing everything necessary to complete it.
Duplicate output doesn’t require duplicate sources
Historically, denormalizing documentation created an obvious maintenance problem. If the same authentication instructions appeared on twenty pages, someone had to keep twenty copies synchronized.
But why should the source and the published documentation have the same architecture? Think about a CMS. A website might have hundreds of pages assembled from shared templates and content components. Change a component, rebuild the site, and every affected page changes. The reader doesn’t care how many pieces produced the page. They receive one cohesive resource.
Agent-facing documentation could work the same way. Authentication and permissions can remain separately maintained sources of truth. A publishing process can use them to produce complete workflows that include the deployment steps.
When authentication changes, change it once. Then rebuild the workflows that depend on it. The source stays normalized while the output becomes denormalized. Instead of making every agent assemble the same information, the publishing process does it once.
Documentation starts looking compiled
This makes documentation look less like a collection of pages and more like compiled output. Source code is organized for maintenance, while compiled software is organized for execution. Nobody expects an executable to mirror the structure of its source code. Why should documentation be any different?
We can structure knowledge around ownership and consistency. Then we can compile that knowledge into self-contained resources organized around the work agents need to perform.
Compiled workflows aren’t the only option though. We still need to support questions we didn’t predict.
Leave less composition to the agent when you can
Many RAG systems retrieve fragments. An agent starts with a task, formulates a query, then receives the pieces that seem relevant. And if something’s missing, it retrieves again.
This gives us flexibility because we don’t need to predict every question. But the consuming agent becomes responsible for composition. The sources may all be authoritative, while the assembled result has never been validated.
For common tasks, we could compile workflows ahead of time. We identify the authoritative knowledge required for each workflow, assemble it into one resource, then validate and publish it. The publisher has done the composition before the agent retrieves anything. But there’s an obvious downside: we need to know which workflows to compile, and the number of possible variations can become enormous.
What if a documentation system could compose a workflow on demand? An agent asks how to deploy service X with authentication Y in environment Z. Rather than returning matching fragments, the system creates one cohesive resource from authoritative knowledge.
That avoids the scavenger hunt, but introduces a validation problem. We can validate every source independently, yet nobody may have reviewed the exact combination the system just produced. Evaluating generated pages means the documentation system has become an AI system with its own evals.
These approaches don’t need to compete. They can form a confidence hierarchy. Use a validated workflow when one exists. When it doesn’t, compose one from authoritative knowledge. For novel problems, let the agent retrieve sources and reason across them.
The more established a workflow is, the less composition we should leave to every consuming agent. Usage can help us decide what to compile next. When agents repeatedly assemble the same workflow, that workflow is a good candidate to become a first-class, validated resource.
Fewer retrievals should be cheaper
Retrieving one complete resource instead of five fragments should usually require fewer tool calls and LLM roundtrips. That should reduce latency and inference cost.
Instead of thousands of agents independently reconstructing the same workflow, we assemble it once and let them use the result. That’s inference efficiency applied to documentation architecture.
There is another benefit that might matter even more. When we publish fragments, we control the fragments, but the agent controls their composition. It might miss one or combine current instructions with outdated guidance. It might also supplement our documentation with information from somewhere else.
With a compiled workflow, the documentation producer controls the complete guidance. And as agents perform more work autonomously, that nuance becomes critical.
But is it more reliable?
Fewer retrieval steps sound like they should make agents more reliable. A self-contained workflow has fewer dependencies to discover and fewer opportunities to retrieve contradictory information. But there are competing effects.
Longer resources put more information into context, so agents might overlook important instructions. Explicit retrieval steps might force useful decomposition. Different models may behave differently, and the right resource size may change with the task.
We shouldn’t turn denormalized documentation into another best practice without testing it. Fortunately, we can.
Take a real workflow from your documentation and create two versions. Leave one fragmented across the existing resources, then create one self-contained workflow. If you have the infrastructure, add a version dynamically composed from the same authoritative knowledge.
Give agents the same task repeatedly and measure whether they complete it correctly. Track the resources they retrieve and the tool calls they need. Measure tokens and elapsed time, then check whether they introduced information from outside your documentation.
Most importantly, compare the quality of the result. A workflow that saves two retrievals but produces worse work isn’t an improvement.
Retest the trade-off
DRY documentation wasn’t an arbitrary convention. Duplication made maintenance expensive, so we centralized information and asked readers to assemble it. That was a reasonable optimization for its time.
But the actors are changing. Agents increasingly consume documentation, and they can help compile it. The cost of producing consistent duplicated output is falling while agents keep paying the cost of retrieving fragmented information.
That doesn’t prove we should denormalize all documentation. It means the old trade-off deserves another test.
Maybe the documentation agents need has normalized knowledge underneath and denormalized workflows on top. Maybe dynamic composition works better, or perhaps good retrieval is enough. We should measure it rather than inherit the answer.