# should docs put agents or humans first?

> ai agents are reading docs. should documentation be written for humans or agents? here's my prediction for the future of docs.

documentation has always been written for humans. but there's a new reader: ai agents.

should docs be written for humans with agent support? or for agents with human readability?

this isn't just theoretical. it's already changing how docs frameworks are built.

## docs still assume a human reader

most documentation is written for humans.

- pretty fonts
- color schemes
- animations and interactive demos
- sidebar navigation with icons
- "get started" cta buttons
- testimonials and social proof

all of this is noise to an agent. the agent can't see the design. it reads the raw text. it gets confused by marketing copy mixed with api reference.

## markdown as the source, html as the skin

agent-first documentation:
- clean markdown as primary format
- structured metadata (`llms.txt`)
- machine-readable navigation
- no marketing fluff
- versioned, url-predictable content

this is what mintlify and fumadocs are building toward. the framework output includes raw markdown by default. the site is a renderer, not the source.

the source of truth is the markdown. the html is a skin.

## why agent-first makes sense

one source of truth is more efficient. write once, render for any channel.

agents can consume the raw docs. humans can view rendered versions. both use the same content.

as agents become more common, agent-first docs will be the standard.

## why human-first still wins

readability: humans need visual hierarchy, examples, and context. raw markdown is readable but not friendly.

discoverability: a beautiful docs site attracts users. raw markdown doesn't.

trust: polished docs signal quality. rough markdown signals "work in progress."

 ## write for humans, expose the source for agents

 the answer is both. write for humans. structure for agents.

 the content should be human-readable. the structure should be machine-readable.

 **what this means practically:**
 - write clear, well-structured markdown
 - include a `llms.txt` file
 - expose raw `.md` endpoints
 - keep the rendered site beautiful

 humans get the pretty version. agents get the raw version. both use the same source.

 ## llms.txt gives agents a way in

 `llms.txt` is the first widely-adopted agent-first standard. a single text file at the site's root that tells agents what's available.

 it's a small step. but it signals intent: "agents can read these docs too."

 current adoption is low but growing fast. mintlify and fumadocs support it natively.

 ## what frameworks are doing

 | framework | agent-readiness |
 |---|---|
 | mintlify | high (`.md` endpoints, llms.txt, nav api) |
 | fumadocs | high (`.md`, llms.txt) |
 | docusaurus | medium (raw md in repo, no exposed endpoints) |
 | gitbook | medium (partial `.md` support) |
 | nextra | high (next.js ± raw file serving) |

 modern frameworks are becoming agent-aware by default.

 ## what agent cache does

 agent cache is a bridge. it takes human-first documentation and converts it to agent-ready format.

 whether the docs are agent-first or human-first, agent cache extracts the useful content and converts it to structured markdown.

 but agent-first sites are easier. when `.md` endpoints exist, extraction is trivial.

 the long-term trend: docs frameworks will expose agent-ready content natively. agent cache will evolve from a converter to a packager.

 ## my bet: hybrid, leaning agent-first

 documentation should always be human-readable. but it should also be machine-consumable.

 the frameworks that do both well will win. mintlify and fumadocs are leading.

 the future: docs sites are for humans. underneath, they're structured markdown with rich metadata. both audiences served.

 ---

 **related:**
 - [mintlify vs docusaurus: framework rankings](/blog/docs-framework-agent-readability)
 - [where to find raw docs before scraping](/blog/acquisition-ladder)