The quick version: Structured technical knowledge is increasingly becoming something AI systems can act on, not just something people or software can read. OpenAPI specifications can expose tools to agents. Product specifications can guide coding agents. Workflow information can help trigger documentation work. That makes documentation architecture more operational. Accuracy, structure, ownership, validation, and versioning matter not only because they affect documentation quality, but because they can also affect what software systems are able to do with that information.
I’ve been thinking about a shift in how structured technical information is being used. For a long time, documentation architecture has been concerned mainly with helping people find, understand, and use information. That still matters. But increasingly, software systems are consuming structured information too, and using it to do something.
An OpenAPI specification might expose API operations as tools an AI agent can call. A product specification might guide a coding agent as it plans and builds software. A product change might trigger an automated documentation workflow.
These are different kinds of information, used in different ways. Still, they seem to point toward a broader change: structured knowledge is becoming something software can use to trigger actions, guide behavior, and shape what happens next.
I’m using “executable knowledge” as a simple shorthand for that idea: information structured in a way that software can act on.
What I find interesting is what this changes about documentation architecture. Accuracy, structure, ownership, validation, and versioning have always mattered. But when software depends on structured information to operate, those choices start to carry operational weight too.
That raises a different kind of question about documentation architecture: what changes when the information we structure isn’t only meant to be read, but can also become part of what a system does?
Machine-Readable Knowledge Isn’t New
Software has been using structured documentation for a long time. OpenAPI specifications can generate API reference pages and SDKs. Metadata can shape navigation, filtering, and search. Structured content can be reused across different outputs, and schemas can check whether information follows an expected format.
So the idea that documentation can be read by machines isn’t new.
What’s different now is the role AI can play after that information is made available. An AI system can use structured knowledge as context for choosing an action, calling a tool, generating software, or starting another process.
The structured information isn’t doing the work by itself. The AI system is acting on it.
That’s the shift I’m interested in here: structured knowledge is becoming more directly involved in what software does next.
An OpenAPI Specification Can Become an Agent Interface
OpenAPI is a useful example of what this shift looks like in practice.
An OpenAPI specification describes an API in a structured format: what operations are available, what inputs they accept, what they return, and other details needed to work with the API. Developers and tools already use that information for things like API reference documentation, SDK generation, testing, and validation.
Now AI systems can use the same specification in a more active way.
Microsoft Azure, for example, can use an OpenAPI specification to expose an application’s API operations as tools through the Model Context Protocol (MCP). An AI agent can then use those tools to interact with the application.
The path looks roughly like this:
API → OpenAPI specification → available tools → agent action
The OpenAPI file hasn’t suddenly become executable code. It’s still describing the API. What has changed is that an AI system can use that structured description to work out which actions are available and how to call them.
That gives the specification another kind of responsibility. It still has to communicate the API clearly to developers, but it may also become part of the information an AI system relies on when deciding what it can do and how to do it.
Machine-Readable Doesn’t Automatically Mean Agent-Usable
There’s an important wrinkle in the OpenAPI example. Giving an AI agent access to a structured specification doesn’t mean the agent will use it well.
A recent study looked at 16 production APIs with about 600 endpoints. The OpenAPI specifications were valid and already supported working software, but agents using those APIs through MCP still struggled to plan tasks, choose the right operations, and build valid requests. The researchers found thousands of issues in the API descriptions that could make the specifications harder for agents to use, including unclear descriptions and missing information about inputs, outputs, security, and behavior.
A smaller experiment within the study makes the problem more concrete. Imagine an API with several operations for managing users. The specification might correctly list GET /users/{id}, POST /users, and PATCH /users/{id}, along with the parameters each operation accepts. A tool can parse that perfectly.
But an agent trying to respond to a request like “update this user’s email address” needs more than a list of valid endpoints. It has to work out which operation is appropriate, which identifier to supply, what the request body should contain, and what authentication or other requirements apply. If those details are vague or missing, the OpenAPI file is still valid, but the agent has much less to work with.
That’s essentially what the researchers tested. They exposed the same API through two MCP servers. One used the existing OpenAPI documentation. The other added clearer descriptions of what each operation did, what information it needed, and what it returned. With the original documentation, most tasks failed during planning. With the improved documentation, the agents were much more successful at choosing the expected operations and completing the tasks.
Though the the API itself hadn’t changed, the information available to the agent had.
Agents Need More Than Valid Structure
This is where the difference between machine-readable and machine-understandable becomes useful. I don’t mean that an AI system “understands” a specification in the way a person does. I mean that being able to parse the structure doesn’t guarantee the system has enough clear information to use it reliably.
That distinction matters if structured knowledge is going to help drive actions. The format can be correct and still leave too much ambiguity about what something does, when to use it, or what it needs. Documentation architecture therefore has to consider more than whether information is structured for machines. It also has to consider whether the system consuming that information has what it needs to act on it.
A Specification Can Guide What Software Gets Built
OpenAPI describes what an existing API can do. A product specification can play a different role: it can help shape what gets built in the first place.
That’s the idea behind spec-driven development (SDD). Instead of asking a coding agent to work from a loose prompt such as “add user authentication,” a team can first describe the intended behavior in more detail: what the feature should do, what requirements it has to meet, what constraints apply, and how the finished work should be checked.
The coding agent can then use that specification as context while it plans the work, writes code, and checks whether the result matches the original requirements. GitHub’s Spec Kit is one example of this approach, treating the specification as the source of truth that guides the development process.
This is a different kind of executable knowledge from the OpenAPI example. The OpenAPI specification helps an agent work with capabilities that already exist. A product specification can help guide the creation or modification of those capabilities.
In both cases, the structured information is doing more than documenting something for a person to read later. An AI system is using it as part of the context that shapes what happens next.
And once that happens, the way the information is written and organized matters in a more direct way. Vague requirements, missing constraints, or unclear relationships between pieces of information can affect the work the agent produces. A well-structured specification gives the system a clearer set of boundaries to work within.
Product Changes Can Set Documentation Work in Motion
A third example comes from documentation workflows themselves.
Microsoft’s Aspire team connected its product repository with its documentation repository using GitHub Agentic Workflows. When a product change is merged, that event can start documentation work in the other repository. The workflow can identify that documentation needs to change, create the corresponding work, and route it back to the engineer who made the product change for review.
The flow is roughly:
product change → workflow trigger → documentation work → engineering review
The interesting part here isn’t that AI can draft documentation. We already know that.
What matters is that the documentation process is becoming connected to the product system itself. A change in one place can trigger work somewhere else, based on rules, repository state, permissions, and ownership.
That means the knowledge around the workflow matters too. The system needs to know what changed, which repository to work in, what it’s allowed to access, who should review the result, and what should happen next.
So this example stretches the idea of executable knowledge a little further. The important information isn’t only in a document or specification. It can also live in workflow rules, repository settings, ownership information, and other structured parts of the system.
Taken together, these examples show the same pattern from different angles: structured technical information is becoming part of how AI systems choose actions, guide work, and move processes forward.
Different Artifacts, Same Pattern
An OpenAPI specification, a product specification, and workflow information are not the same kind of artifact. They serve different purposes, use different structures, and may be owned by different teams.
But the pattern across them is similar. An OpenAPI specification can help an agent work out which actions are available and how to call them. A product specification can guide what a coding agent builds. Workflow information can help determine what process starts next and who needs to review the result.
In each case, structured technical information is becoming part of what the system uses to move from one step to another.
That’s what I mean here by executable knowledge. The knowledge itself isn’t code, and it isn’t acting on its own. But an AI system can use it as context for taking action.
That distinction matters because it keeps the idea broad enough to cover different kinds of technical knowledge without pretending they all work the same way.
The common thread is simpler: once software can act on structured information, the way that information is designed starts to matter operationally as well as informationally.
Documentation Architecture Starts Carrying Operational Weight
This is where the shift starts to matter most to me. Documentation architecture has always shaped how information is organized, maintained, and reused. It helps people find the right thing, understand how pieces relate, and trust that what they’re reading is current.
When software can act on that information, those same choices start to affect more than the reading experience.
Accuracy
Accuracy becomes part of how reliably the larger system works. If an API description is wrong, an agent may call the wrong operation or build the wrong request. If a product specification leaves out an important constraint, a coding agent may produce something that technically works but doesn’t match the intended behavior.
The information has to represent the system, or the intended system, clearly enough for another system to use it.
Structure
Structure matters for a similar reason. It’s not enough for information to exist somewhere. The system consuming it has to be able to find the relevant pieces, tell how they relate, and distinguish one kind of information from another.
The OpenAPI research makes this especially clear. A specification can be valid and machine-readable while still giving an agent too little useful information to act reliably.
So structure has to support use, not just storage.
Ownership
Once other systems depend on structured knowledge, ownership becomes more important too. Someone has to know who is responsible for keeping that information current, who reviews changes, and what happens when the underlying product changes.
That responsibility may cross team boundaries. An API specification, for example, might support developer documentation, SDK generation, testing, and agent tools at the same time.
Validation
Validation also starts to mean more than checking whether the format is correct. A schema can tell you that a file follows the expected structure. That doesn’t necessarily tell you whether an agent can use the information successfully.
Teams may also need to check what happens downstream: does the agent choose the right operation, follow the intended workflow, or produce the expected result?
Versioning
Versioning becomes another part of keeping the system aligned. If the product changes but the specification doesn’t, or the workflow changes but the instructions around it don’t, the different parts of the system start to drift apart.
That has always been a documentation problem. The difference is that now the stale information may be feeding directly into automated behavior.
None of these concerns are new on their own. Accuracy, structure, ownership, validation, and versioning have always mattered.
What’s changing is the role they can play. They’re becoming part of the conditions that help AI systems act reliably on technical knowledge.
Documentation Architecture Has to Account for Consumers Other Than Readers
Documentation architecture has usually been built around questions like these:
- What information do people need?
- How should it be organized?
- Where should it live?
- How should different pieces connect?
- How do we keep it reusable and current?
Those questions still matter. But they’re no longer the whole picture.
If AI systems and other software can use structured technical knowledge as part of what they do, documentation architecture also has to account for those systems as consumers.
That adds a different set of questions:
- What software systems use this information?
- What structure do they expect?
- What details do they need in order to use it reliably?
- What actions can they take because of it?
- What depends on the information staying current?
- How do we know a change hasn’t broken something downstream?
This doesn’t mean every document needs to be redesigned for machines. It means we have to understand where information sits in the larger system and who, or what, depends on it.
A page written only for a person has one set of design concerns. A specification that also feeds an agent, a generator, or an automated workflow has another.
That’s why documentation architecture starts to carry more weight when structured knowledge becomes executable. The architecture is no longer shaping only how information is read. It can also shape how information moves through software systems and what those systems are able to do with it.
Structured Knowledge is Becoming Operational
Structured knowledge has been part of software systems for a long time. What’s changing is how directly AI can use that knowledge to shape action.
That makes documentation architecture more consequential. The way information is structured, maintained, validated, and kept in sync can affect not only what people read, but what software systems are able to do with that information.
I think that’s the more useful way to think about “executable knowledge.” The important change isn’t that documentation has somehow turned into code. It’s that structured technical knowledge is becoming more closely tied to software behavior.
And once that happens, documentation architecture becomes part of the operational system around the software, not only the layer that explains it.
Leave a Reply