When AI Becomes a Documentation Consumer

Exploring how to derive AI-oriented knowledge representations without duplicating documentation.

Same knowledge. Different consumers. Different representation requirements.

Technical documentation has already undergone a major change in how it is consumed.

Documentation once meant a relatively static resource, often designed to be read sequentially. With the Web, it became searchable, interconnected and accessible at page or section level. Docs-as-code and continuous delivery went further, making documentation part of an evolving software lifecycle.

Another change is now taking place:

documentation consumers are no longer exclusively human.

AI systems retrieve, interpret, combine and reuse documentation.

Sometimes they act as an interface between knowledge and a human user, through a RAG system, chatbot or documentation agent.
In other situations, knowledge may be consumed by machines with little or no human-facing representation involved.

This introduces new consumption patterns and constraints.

AI is not only a documentation tool. It is becoming a documentation consumer.

The question is therefore no longer simply how to give AI access to existing documentation, but whether the representations we designed for humans are also appropriate for machine-first consumption.

AI as a New Documentation Consumer

           ██╗  ██╗███╗   ██╗ ██████╗ ██╗    ██╗██╗     ███████╗██████╗  ██████╗ ███████╗
           ██║ ██╔╝████╗  ██║██╔═══██╗██║    ██║██║     ██╔════╝██╔══██╗██╔════╝ ██╔════╝
           █████╔╝ ██╔██╗ ██║██║   ██║██║ █╗ ██║██║     █████╗  ██║  ██║██║  ███╗█████╗  
           ██╔═██╗ ██║╚██╗██║██║   ██║██║███╗██║██║     ██╔══╝  ██║  ██║██║   ██║██╔══╝  
           ██║  ██╗██║ ╚████║╚██████╔╝╚███╔███╔╝███████╗███████╗██████╔╝╚██████╔╝███████╗
           ╚═╝  ╚═╝╚═╝  ╚═══╝ ╚═════╝  ╚══╝╚══╝ ╚══════╝╚══════╝╚═════╝  ╚═════╝ ╚══════╝  

Documentation architecture has always been influenced by its audiences.

Human-facing documentation combines information with features designed to support human understanding: navigation, progressive explanations, visual hierarchy, interactive components, illustrations and diagrams.

Some of these features remain useful to AI systems. Others are primarily presentational, or become difficult to interpret when individual fragments are retrieved outside their original interface.

Conversely, information that does not always need to be explicitly displayed to a human reader may be highly useful to a machine: provenance, authorship, last modification date, lifecycle status, version compatibility, relationships between concepts or other qualification signals.

note

Accessibility provides an interesting overlap. Information originally designed to improve accessibility for humans — alternative text or semantic structure, for example — may also make content more explicit for machines.

This does not mean that AI needs simplified documentation.

Removing explanations merely to save tokens can also remove context. Meaning and context remain essential. What changes is the way some information may need to be exposed, structured or qualified.

The representation should therefore depend on the task:

An agent answering documentation questions, a retrieval pipeline building an index, a coding agent exploring a repository and an autonomous process consuming knowledge through an interface do not necessarily need the same representation.

When AI becomes a documentation consumer, representation becomes an architecture decision.

Designing for AI Consumption

Before creating any AI-specific representation, the first question should be: what does the intended consumer actually need?

In some cases, existing documentation may already provide enough structure and context. In others, relevant information exists but remains implicit. Some information may need to be added specifically for machine consumption.

Assessing Available Information

Designing an AI-oriented representation therefore means identifying:

what already exists, what should be preserved, what should be made explicit, and what needs to be added.

Available information	Why it matters for AI	Possible treatment
Content and explanations	Provide meaning and domain knowledge	Preserve
Titles and descriptions	Identify and summarize resources	Preserve or enrich
Hierarchy and navigation	Provide contextual relationships	Make explicit where useful
Authorship and modification dates	Support provenance and freshness	Expose as metadata
Versions and lifecycle status	Help qualify applicability	Expose consistently
Relationships between concepts	Support retrieval and reasoning across resources	Encode explicitly
Taxonomies and controlled terminology	Improve consistency and discovery	Reuse and govern
Interactive UI elements	May hide or fragment information	Transform when required
Decorative layout and visual chrome	Primarily presentation-oriented	Usually omit from derived representations
Diagrams and other non-prose information	May contain essential technical knowledge	Preserve in interpretable form

Meaning and context should not be replaced by metadata. Metadata should help machines qualify and connect the underlying knowledge.

Experience Note

Prefer text-native representations when possible

In my technical documentation, I generally prefer Mermaid diagrams over PNG diagrams when they can preserve the same meaning.

The source remains text-based, versionable and transformable, while humans still receive a visual representation.

This does not guarantee that an AI system will correctly interpret every Mermaid diagram. But it provides both human and machine consumers with access to the information underlying the visual representation.

Existing Approaches to AI-Oriented Documentation

The idea of supplying machines with a representation different from the human-facing one is not new.

Several approaches are already emerging.

Markdown Twins

I use Markdown Twin here to describe a plain-text Markdown representation of content that is also published in another form, typically HTML.

A documentation page designed for humans may contain navigation, layout components, styling, scripts and interactive elements. A Markdown representation can remove much of this visual and interface complexity while exposing content in a simpler textual structure.

The value of such a representation is not only the Markdown format itself.

It can provide less presentation noise, more explicit structure, relationships, context and machine-relevant metadata.

This approach can be useful for a documentation website whose published HTML is much more complex than its underlying content.

But it immediately raises a question when the original source is already Markdown, reStructuredText, AsciiDoc or another structured text format:

what additional value does the Twin provide?

llms.txt

Jeremy Howard introduced llms.txt in 2024 as a proposed way of helping agents discover and navigate LLM-friendly content on websites.

The file acts primarily as a machine-oriented entry point: it supplies context and links to relevant resources rather than duplicating an entire website.

Version 2, published in August 2026, also formalizes discovery of Markdown page alternatives. Its author reports adoption by thousands of sites and several documentation platforms.

However, this remains a proposal rather than a universal Web standard.

Google Search clarified in June 2026 that llms.txt is not required for Google Search and has neither a positive nor negative effect on Search visibility or ranking. It may nevertheless remain useful for other services and agents that choose to consume it.

So the important signal is not that one convention has already won.

It is that several conventions and implementations are appearing because machine consumption is becoming a real documentation use case.

Different Documentation Environments, Different Problems

The relevance of an additional representation also depends heavily on where documentation lives.

Experience Note

Not all documentation starts from the same place

Across technical documentation projects, I have worked with several patterns:

documentation clearly separated from the product, such as Confluence knowledge bases;
docs-as-code documentation maintained in Git repositories;
documentation closely connected to code or generated from it, such as API descriptions and code documentation;
hybrid technical resources such as Python notebooks, combining executable content and explanations.

Creating an additional representation has very different implications in each case.

Limitation 1 — Moving Knowledge into Another Format

Creating a Markdown representation may require extracting knowledge from its authoring environment and converting it into another format.

For a Confluence knowledge base, this means both leaving the original platform and translating its structures.

Even between text-based documentation formats, such as reStructuredText, AsciiDoc and Markdown, transformation introduces another processing step.

AI can assist with conversion, but the conversion still needs to preserve structure, meaning and relationships.

Limitation 2 — Creating Another Corpus

A Twin can become exactly what its name suggests: a duplicate.

This is particularly problematic when the original knowledge base contains the inconsistencies, duplicated information, obsolete pages or governance issues that had to be resolved to make the knowledge trustworthy in the first place.

Limitation 3 — Who Owns the Twin?

A second corpus also creates a lifecycle problem.

Who generates it?
Who validates it?
Who updates it when its source changes?
Who verifies that both representations remain aligned?

And if AI performs these maintenance tasks, who validates the AI-generated output?

These are documentation governance questions, not simply format-conversion questions.

Derive, Don't Duplicate

My alternative is to treat the machine-oriented representation as a derived artifact, rather than an independently maintained documentation corpus.

The principle is simple: Derive, don't duplicate.

From Principle to Process

Instead of manually maintaining a second version, a controlled process can select, combine, reorganize or enrich knowledge from authoritative sources according to predefined consumption requirements.

Those consumers may include humans with different information needs, agents, retrieval and indexing systems, coding assistants or other machine processes.

The resulting representation might be:

generated during a documentation build;
refreshed when authoritative knowledge changes;
assembled dynamically;
stored and versioned as an artifact;
or exposed through an interface when needed.

This does not eliminate all risks.

A transformation can introduce errors. Generated summaries can distort meaning. Metadata can become inconsistent. Automated pipelines need validation.

A Different Responsibility Model

Derivation also changes where authority and responsibility sit.

The knowledge remains authoritative at its source. The derived representation becomes an output with traceable inputs, transformation rules and lifecycle.

This logic already exists in other technical publishing workflows: docs-as-code build pipelines, generated API references, structured-data generation and other derived artifacts.

The same principle can be extended to AI-oriented representations.

Building an AI-Oriented Representation

My own approach to this question did not begin with an AI knowledge format.

It emerged from earlier work on structured data, SEO and GEO, then from my work on agentic documentation, AI-ready knowledge and docs-as-data.

From Structured Data to AI-oriented Knowledge

On CoffeeCup.tech, I developed a Docusaurus plugin that generates structured data for individual pages.

The mechanism combines two types of information:

shared information defined centrally;
page-specific information retrieved from front matter.

The plugin assembles these elements into JSON-LD and injects the resulting structured data into the page <head>, where it is intended for a specific machine audience: search engines and indexing systems.

The human reader does not see that representation.

Yet it describes the same content.

This mechanism made another architectural possibility appear logical to me.

I believe the same principle can be extended beyond structured data to AI-oriented knowledge representations.

The structured-data implementation distributes information where it is most appropriate to maintain it, then assembles a machine-oriented representation automatically.

That same logic could be reused on a broader scale for AI consumption.

Reuse what already exists. Add only what AI consumption requires. Assemble the representation automatically.

Reuse Existing Knowledge and Metadata

Documentation already contains information that can be reused.

Titles, descriptions, taxonomy, versions, existing relationships, content type, authorship, dates, code references and other metadata can contribute to a machine-oriented representation.
Some information belongs to the whole knowledge system.
Other information belongs to one specific resource.

info

The architecture does not need to duplicate shared information in every document. A transformation pipeline can assemble global information and source-specific information, as my structured-data plugin already does for JSON-LD.

Qualify and Connect, Don’t Replace

The important point is that metadata should qualify and connect the knowledge rather than replace it.

For example, identifying a page as an installation procedure is useful. But the consumer must still be able to access the installation procedure itself, together with its prerequisites and applicable conditions.

Consider the Authoring Environment

The possibilities also depend on the authoring environment.

Markdown-based docs-as-code environments make custom metadata particularly easy to maintain through front matter.
Knowledge platforms such as Confluence, Notion or SharePoint generally offer a different and sometimes more constrained metadata model, so additional information may need to be stored or derived differently.

Add AI-Specific Knowledge and Metadata

When existing information is insufficient, several strategies are possible.

Enrich front matter

Markdown front matter can hold additional structured fields as long as the processing system knows how to interpret them.

A documentation architecture could therefore introduce fields describing relationships or content semantics, for example:

documentationType: installation
isPartOf: getting-started
relatedTo:
  - prerequisites
  - configuration

The technical ability to add arbitrary YAML fields is not the difficult part.

The architectural question is whether their meaning is defined consistently enough for producers and consumers to understand them.

Existing vocabularies can help. Schema.org, for example, already provides relationships such as isPartOf, hasPart, isBasedOn and about.

Experience Note

From structured data to knowledge relationships

This question was already familiar to me from my work on structured data. While reviewing the Schema.org vocabulary for CoffeeCup.tech, I explored how relationships, types and metadata could describe documentation content beyond what is directly visible on the page.

I had already started exploring this question in January 2026 in my blog article "Structured Data and Documentation Sites". This work later became one of the foundations for my thinking about AI-oriented documentation.

But a documentation-specific AI representation may also need concepts that are not covered by a generic Web vocabulary.

This was one of the questions I was asking before exploring the Open Knowledge Format (see below): how much knowledge semantics can or should be encoded in front matter, and who defines the vocabulary?

Embed Additional Structured Knowledge in the Content

For environments where custom metadata is difficult to manage, useful machine-oriented information could also be embedded within the documentation itself.

This might take the form of:

a structured summary;
standardized headings;
a visible knowledge block;
or a fragment specifically designed for both human and machine consumption.

info

This approach may be especially relevant for knowledge bases such as Confluence, Notion or SharePoint, where front-matter-style customization is less natural.

Store Dedicated Knowledge Resources Elsewhere

Some AI-specific resources may also be maintained separately when they do not naturally belong to an individual documentation page.

They could include shared definitions, cross-document relationships, contextual summaries or other structured knowledge.

An MCP server could then expose those resources to an agent.

In this architecture, MCP is a consumption and exposure mechanism, not the knowledge representation itself.

Separate knowledge from representation

Derivation starts with identifying what is actually being derived: not the page itself, but the knowledge it carries and qualifies.

This fits naturally with a docs-as-data approach.

Documentation can then be considered through several layers.

Knowledge layer — Facts, explanations, data, code, metadata, context and relationships.
Presentation layer — Branding, layout, visual hierarchy, interactions and accessibility affordances.
Representation layer — Markdown, HTML, JSON, YAML, graphs, hierarchy and navigation structures.
Consumption layer — How humans or machines traverse, combine and act on those representations.

These layers overlap.

Accessibility is a good example: alternative text or semantic HTML primarily helps people access content, but the additional semantics can also benefit machines.

A loose parallel can also be drawn with APIs: the underlying resource does not necessarily change because different representations or interfaces expose it to different consumers.

Separating these layers does not imply that they should all be physically separated.

It simply makes their different responsibilities explicit.

From Knowledge Sources to AI Representations

Once knowledge, representation and consumption are considered separately, several pipeline architectures become possible.

The objective is not necessarily to create one physical source of knowledge.

It is to establish a governed knowledge foundation from which appropriate representations can be produced.

Three simplified patterns illustrate the possibilities.

Single-Source Derivation

One Source to One Representation

A single documentation environment remains authoritative.

Authoritative documentation ──> Transformation specification ──> AI-oriented representation

For example, a documentation website or Confluence knowledge base could be transformed into a representation enriched with additional metadata, explicit relationships or structured summaries.

The key point is that the derived representation is generated according to defined input, processing and output rules.

This is the architecture closest to the original Twin idea, but without independently maintaining the Twin.

Knowledge Aggregation

Many Sources to One Representation

Knowledge may already be distributed across several authoritative sources.

Confluence ──────────┐
Git repository ──────┼──> Aggregation / qualification ──> AI representation
Shared metadata ─────┤
Other resources ─────┘

The objective is not to copy everything into a new authoring environment.

The pipeline combines relevant information from several locations to provide a coherent consumption layer.

This may be particularly relevant for heterogeneous documentation ecosystems where technical knowledge is distributed between product documentation, code repositories and knowledge bases.

Multi-Representation Publishing

One Foundation to Many Representations

A more ambitious and prospective architecture places structured knowledge earlier in the lifecycle.

Governed knowledge foundation --+--> Human-facing documentation
                                +--> AI-oriented representation
                                +--> Search / other representation

Human-facing and machine-oriented outputs then become alternative representations produced from the same governed foundation.

info

This model may be particularly interesting when designing a new docs-as-code or docs-as-data architecture rather than adapting an existing documentation estate.

It also raises more difficult questions about authoring workflows, source ownership, validation and how structured that common foundation should become.

note

My diagrams above are deliberately simplified.

The three architectures can coexist, and organizations may progressively move from derivation of existing documentation toward a more structured common knowledge foundation.

Governance and Lifecycle

Adding machine-oriented information creates documentation governance responsibilities.

This is especially important when content has multiple authors.

note

If authors independently create values for documentationType, relationships, status fields or summaries, the machine-oriented layer can develop the same inconsistencies as the human-facing documentation.

Metadata therefore requires governance too.

Possible controls include:

controlled vocabularies;
naming conventions;
schemas;
validation rules;
ownership;
source-of-truth rules;
synchronization processes;
lifecycle status;
monitoring;
retirement rules.

Automation can reduce repetitive work, but it should not remove accountability.

The Technical Writer's Role

This architecture also reinforces the role of an expert technical writer.

The work is not limited to producing prose.

A technical writer can:

identify and qualify authoritative knowledge;
restructure content;
design and govern metadata;
define relationships and contextual information;
create AI-oriented summaries;
design agent knowledge surfaces;
specify inputs and expected outputs;
validate generated representations;
contribute to transformation pipelines;
and maintain consistency throughout the documentation lifecycle.

Technical implementation may require collaboration with engineering, data or AI teams.

But the documentation architecture, information model and quality rules remain documentation concerns.

Experience Note

Still an architecture to test

The approaches presented here are currently architectural hypotheses rather than the results of a completed implementation.

My next step is to experiment with them in practice, either through future documentation projects or through the development of my own personal AI-oriented knowledge base.

The objective will be to test where derivation works, which information is actually useful, how much metadata is necessary and where automation creates value rather than additional complexity.

Emerging Approaches and Open Questions

My thinking about AI-oriented representations developed progressively through several areas of my work:

structured data → agentic documentation → AI-ready knowledge → AI-oriented representation

Only afterwards did I explore emerging initiatives that address some of the same questions.

This chronology matters.

The architectural principle described above was not derived from OKF. Instead, OKF provides an interesting external framework against which these ideas can now be compared.

Open Knowledge Format (OKF)

Google introduced the Open Knowledge Format in June 2026 as an open specification formalizing what it calls the LLM-wiki pattern.

Google describes OKF as an:

"agent- and human-friendly standard for representing the metadata, context, and curated knowledge that modern AI systems need."

OKF represents knowledge through Markdown documents and YAML front matter. Its current v0.2 specification makes provenance, trust, freshness and lifecycle first-class concerns, while deliberately remaining extensible.

This is particularly interesting in relation to the questions raised earlier in this page.

OKF requires a type field but allows producer-defined metadata and requires consumers to tolerate unknown additional fields. It therefore provides one possible answer to the question of how documentation-specific knowledge semantics can be added without requiring a universal schema for every concept.

It also explicitly distinguishes producers — humans, agents or export pipelines — from consumers such as agents, user interfaces, search indexes or deterministic code.

That separation closely matches the producer / representation / consumer architecture explored here.

OpenWiki

OpenWiki provides a more concrete implementation perspective.

LangChain describes it as an open-source CLI that creates and maintains Markdown wikis about codebases or personal knowledge.

Its documentation states:

“Humans can browse the same Markdown [...] but the primary audience is agents.”

That sentence captures an important idea: machine-oriented documentation does not necessarily have to be unreadable by humans. It can remain human-readable while being architected primarily for machine consumption.

OpenWiki can produce OKF v0.2 bundles, preserve producer-defined extension fields and maintain provenance and verification information. It also uses Markdown links to express relationships between concepts.

Its treatment of diagrams is equally interesting: OpenWiki generates Mermaid diagrams when they clarify information and validates their syntax. This aligns with the preference for text-native representations discussed earlier.

The project also includes a visualizer that exposes the same Markdown wiki as an interactive node graph and document reader — an interesting example of one knowledge corpus supporting another form of exploration.

Very Recent Approaches

These initiatives are still very recent.

There is not yet enough long-term evidence to assess their maintenance cost, interoperability, adoption patterns or suitability across different documentation environments.

info

The current OKF specification itself notes that knowledge representation for AI agents is evolving rapidly and that incompatible conventions are appearing.

That makes experimentation particularly important.

Questions I want to explore include:

How reliably can heterogeneous documentation be transformed while preserving meaning and provenance?
Which existing metadata actually improves AI consumption?
How much AI-specific metadata is useful before it becomes another maintenance burden?
How should relationships between documentation resources be represented?
How can multi-author environments maintain consistent metadata and summaries?
When is enriching existing documentation sufficient?
When does a separate generated knowledge bundle create real value?
How should generated representations be validated and synchronized?
Can standards such as OKF provide practical interoperability between documentation systems and AI consumers?

More to come

These approaches are part of my next experimentation work, with implementation feedback to be documented in the Blog.

The evolution will probably be progressive rather than a complete redesign of existing documentation systems: progressively enriching existing knowledge sources while introducing machine-oriented representations where they provide measurable value.

Conclusion — Documentation Has a New Consumer

For several years, my documentation work has involved paying attention to two complementary dimensions of published content:

what humans see and use, and what machines can read behind or alongside it.

Front matter has long provided key information both for the internal functioning of documentation websites and for search-engine indexing.
Structured data made the human-vs-machine distinction explicit for search engines.
Docs-as-data extended it by treating structure and metadata as meaningful parts of documentation.
Agentic AI showed how AI systems actively consume documentation.
AI-ready knowledge highlighted the need for trustworthy content, qualification signals and governance.

The next question follows naturally:

what changes when AI itself becomes a documentation consumer?

My current answer is not to create a second documentation corpus by default.

It is to start from governed knowledge, understand the intended consumer, reuse existing information, add only what is required, and derive appropriate representations through controlled processes.

Emerging initiatives such as OKF and OpenWiki suggest that similar questions are now being explored more broadly.

The architectures and standards are still evolving.

But the shift in audience is already here.

Design documentation for humans. Architect knowledge for every consumer.

© Author: Florence Venisse, Technical Documentation & AI Expert – First version dated Octobre 09, 2026

AI as a New Documentation Consumer​

Designing for AI Consumption​

Assessing Available Information​

Existing Approaches to AI-Oriented Documentation​

Markdown Twins​

llms.txt​

Different Documentation Environments, Different Problems​

Limitation 1 — Moving Knowledge into Another Format​

Limitation 2 — Creating Another Corpus​

Limitation 3 — Who Owns the Twin?​

Derive, Don't Duplicate​

From Principle to Process​

A Different Responsibility Model​

Building an AI-Oriented Representation​

From Structured Data to AI-oriented Knowledge​

Reuse Existing Knowledge and Metadata​

Qualify and Connect, Don’t Replace​

Consider the Authoring Environment​

Add AI-Specific Knowledge and Metadata​

Enrich front matter​

Embed Additional Structured Knowledge in the Content​

Store Dedicated Knowledge Resources Elsewhere​

Separate knowledge from representation​

From Knowledge Sources to AI Representations​

Single-Source Derivation​

Knowledge Aggregation​

Multi-Representation Publishing​

Governance and Lifecycle​

The Technical Writer's Role​

Emerging Approaches and Open Questions​

Open Knowledge Format (OKF)​

OpenWiki​

Very Recent Approaches​

Conclusion — Documentation Has a New Consumer​

AI as a New Documentation Consumer

Designing for AI Consumption

Assessing Available Information

Existing Approaches to AI-Oriented Documentation

Markdown Twins

llms.txt

Different Documentation Environments, Different Problems

Limitation 1 — Moving Knowledge into Another Format

Limitation 2 — Creating Another Corpus

Limitation 3 — Who Owns the Twin?

Derive, Don't Duplicate

From Principle to Process

A Different Responsibility Model

Building an AI-Oriented Representation

From Structured Data to AI-oriented Knowledge

Reuse Existing Knowledge and Metadata

Qualify and Connect, Don’t Replace

Consider the Authoring Environment

Add AI-Specific Knowledge and Metadata

Enrich front matter

Embed Additional Structured Knowledge in the Content

Store Dedicated Knowledge Resources Elsewhere

Separate knowledge from representation

From Knowledge Sources to AI Representations

Single-Source Derivation

Knowledge Aggregation

Multi-Representation Publishing

Governance and Lifecycle

The Technical Writer's Role

Emerging Approaches and Open Questions

Open Knowledge Format (OKF)

OpenWiki

Very Recent Approaches

Conclusion — Documentation Has a New Consumer