agent-first documentation: writing for machines that read like humans

by Ray Svitla

documentation has always been written for humans. that assumption is breaking.

AI agents are reading your docs. they’re using them to understand your API, your codebase, your product. they’re better at finding information than most humans, but worse at dealing with ambiguity.

if your docs are full of implied context, vague references, and “as mentioned earlier” — agents will miss things. if your docs are structured clearly with explicit relationships — agents will be eerily good at using them.

the question isn’t whether to optimize for agents. they’re already reading. the question is whether to help them understand.

the semantic chunking problem

humans read documents linearly (mostly). we build context as we go. we remember what we read three paragraphs ago.

agents process documents in chunks. they don’t have the full context. they have whatever chunk the retrieval system gave them.

this creates weird gaps.

example: your API docs say “use the token from the previous step.” but the agent only sees this section, not the previous step. now it’s confused.

agent-first docs make every chunk self-contained. not “use the token from above” but “use the authentication token you received from the POST /auth/login endpoint.”

yes, it’s more verbose. but it’s also more robust to chunked retrieval.

explicit over implied

human-friendly doc: “now that you’ve set up authentication, you can make requests”

agent-friendly doc: “after obtaining an authentication token via POST /auth/login, include it in the Authorization header of subsequent requests as: Authorization: Bearer {token}”

the difference isn’t technical accuracy. both are accurate. the difference is explicitness.

agents are very literal. they don’t infer. they don’t assume. if you don’t say it explicitly, they won’t know it.

this is actually good for human readers too. explicit documentation is clearer. but it takes more words, which humans complain about.

trade-off: clarity vs brevity. for agent-first docs, clarity wins.

structured metadata: the invisible layer

humans read text. agents read structure.

markdown is great because it has semantic structure: headers, lists, code blocks. but you can add more.

frontmatter metadata helps agents understand what a document is about before processing the full text:

---
type: api-reference
endpoint: POST /users
requires: authentication
returns: user-object
related: [GET /users/:id, DELETE /users/:id]
---

now an agent can decide if this doc is relevant without reading the whole thing. and it knows what other docs might be helpful.

this is like alt text for docs. humans don’t see it, but it makes the content accessible to different consumers.

linking: explicit relationships matter

human docs: “see the authentication guide for setup instructions”

agent docs: “see authentication setup for instructions on obtaining API keys”

the difference: → explicit path (not ambiguous) → specific scope (setup, not the whole auth guide) → concrete outcome (obtaining API keys)

agents can follow explicit links. they struggle with vague references.

also: bidirectional linking helps. if doc A mentions doc B, make sure doc B has a “related” section that includes doc A.

this creates a navigable knowledge graph instead of a pile of isolated documents.

code examples: executable, not decorative

human-focused code examples often skip setup, assume context, or show idealized versions.

# human-friendly example
user = api.get_user(123)

agent-friendly version:

# complete, runnable example
import api_client

# authenticate first (see /docs/auth)
client = api_client.Client(api_key="your_key_here")

# fetch user by ID
user = client.get_user(user_id=123)

# user object structure: {id: int, name: str, email: str}
print(user.name)

the second version: → shows imports → references auth docs → includes concrete values → documents return type → demonstrates usage

agents can use this directly. they can also extract structured information: “this operation requires authentication, returns an object with id/name/email fields.”

FAQ as structured knowledge

FAQs are usually just lists of questions and answers. fine for humans browsing.

for agents, structure them as a knowledge base:

- question: "how do I handle rate limits?"
  answer: "API returns 429 when rate limit exceeded. Retry after value in Retry-After header."
  tags: [rate-limiting, errors, http-429]
  related: [error-handling, api-limits]

now agents can: → search by tags → find related info → extract structured facts (429 status code → rate limit)

error messages: documentation in the wild

error messages are documentation. users see them when something breaks. agents see them when they need to debug.

bad error: “invalid request”

good error: “invalid request: email field is required and must be a valid email format (e.g., user@example.com )”

better error: “invalid request: missing required field ’email’. Expected format: user@example.com . See /docs/api/users#email-validation for details.”

the best error includes: → what went wrong → what was expected → example of correct format → link to relevant docs

agents can parse this. they can fix the error and retry. or they can fetch the linked docs to understand the requirement better.

versioning: explicit, not implied

human docs might say “in recent versions” or “as of 2.0.”

agent docs say “supported in versions ≥2.0.0” and include structured version metadata.

when an agent is working with your API, it needs to know what’s available in the version it’s using. fuzzy language doesn’t help.

even better: version-aware documentation. the docs detect which version you’re using and show only relevant information.

this is harder to maintain but massively better for both humans and agents.

the searchability problem

agents don’t read docs linearly. they search.

if your important information is buried in the middle of a long page, humans might find it by scanning. agents will only find it if the search/retrieval system surfaces that chunk.

this means: → important points should be in headers or summaries → key information should be repeated where relevant → cross-references should be explicit

think about docs as a graph that gets traversed, not a book that gets read cover-to-cover.

semantic chunking strategies

when your docs get embedded into a vector database for RAG (retrieval augmented generation), chunking matters.

bad chunking: split every 500 characters regardless of structure.

good chunking: split on semantic boundaries (headers, sections, topic changes).

better chunking: overlap chunks slightly so context isn’t lost at boundaries.

most doc systems don’t control this. but if you’re building agent-first documentation intentionally, chunking strategy is a first-class concern.

when human-first and agent-first conflict

sometimes they don’t conflict. explicit, well-structured docs are good for everyone.

but sometimes they do. humans want narrative flow, personality, humor. agents want structured facts, explicit relationships, semantic clarity.

my take: optimize for clarity first, personality second. a boring doc that works is better than a delightful doc that confuses.

or: write human-friendly explanations with agent-friendly structure. narrative in the body, metadata in the frontmatter.

the meta-documentation layer

here’s the weird future: documentation about your documentation.

a high-level doc that tells agents: → what kinds of docs exist → how they’re organized → what to read first → what’s most reliable vs experimental

humans build this mental model by exploring. agents need it written down.

think of it as a README for your docs themselves.

testing docs with agents

you test code. why not test docs?

write test cases: → “agent should be able to figure out how to authenticate” → “agent should find rate limit information” → “agent should understand error 403 forbidden”

then see if an agent with access to your docs can answer these questions correctly.

if it can’t, your docs have gaps.

this is a new kind of documentation QA. not “is it accurate?” but “is it usable by autonomous systems?”

the ultimate goal: self-serve agents

the dream: an agent encounters your API, reads your docs, and successfully uses it without human intervention.

we’re not there yet for complex systems. but for simple APIs? it’s working.

I’ve watched Claude Code read API docs, understand authentication, make requests, handle errors, and accomplish tasks — just from documentation.

when docs are good, it works. when docs are vague or incomplete, agents get stuck just like humans do.

the difference: humans can guess or improvise. agents just fail.

have you seen examples of really good agent-friendly documentation? or really bad attempts? what made the difference?

Ray Svitla stay evolving 🐌