Writing Docs LLMs Can Use

Two audiences, one source

Documentation now serves two readers: the developer, and the AI systems answering that developer's questions. The second reader consumes more of your docs than any human ever will, and it decides what to quote.

The good news: the two audiences want almost the same thing. Clear structure, self-contained explanations, runnable code. The difference is tolerance. A human recovers from a vague heading or a screenshot of code; a retrieval pipeline just returns someone else's page instead.

llms.txt and llms-full.txt

The llms.txt convention gives AI systems a machine-friendly entry point to your site:

• /llms.txt is a Markdown index: the site's name, a one-line summary, and a curated list of links with descriptions. It tells an agent what exists and where, without HTML noise.
• /llms-full.txt inlines the full documentation content as one Markdown file, for consumers that want everything in a single fetch.

This site practices what this page preaches: devrel.directory/llms.txt is the live index, and devrel.directory/llms-full.txt is the full-content mirror. Every docs page here is also available as raw Markdown by appending .md to its URL, and the page actions above let you copy the page or open it in an assistant directly.

Two honest caveats belong next to any llms.txt advice:

1. Adoption by AI vendors is uneven and changing; treat llms.txt as cheap insurance and a clear signal of intent, not a guaranteed pipeline.
2. An llms.txt that promises pages which 404, or describes content that no longer exists, is worse than none. Generate it from your real content, never by hand.

Structure that retrieves well

Retrieval systems pull chunks, not sites. Whether your content surfaces depends on how well each chunk stands alone:

1. One concept per page. A page that answers one question cleanly beats a mega-page where the answer hides in section four.
2. Self-contained sections. Each heading plus its content should make sense without the surrounding page, because that is exactly how it will be quoted. Write headings that state the topic ("Rotate an API key") rather than tease it ("Keeping things secure").
3. Descriptive frontmatter. Titles and descriptions become index entries, search snippets, and llms.txt lines; write them as accurate one-line summaries, not slogans.
4. Code blocks with language tags. Tagged blocks survive Markdown conversion and tell every consumer what they are looking at.
5. Text, not pixels. Content locked inside interactive components, videos without transcripts, or images of terminal output is invisible to most of this pipeline. Interactive elements can stay, but the information in them must also exist as text.
6. Stable anchors. Heading anchors are how deep links and citations survive; renaming them casually breaks both.

Markdown-first distribution

The durable strategy underneath all of this: keep a plain Markdown mirror of your documentation and let machines fetch it.

• Serve each docs page as raw Markdown at a predictable URL, next to the HTML version.
• Keep the mirror generated from the same source as the site, so it can never drift.
• Make copy-for-AI trivial: a copy-as-Markdown action on every page costs little and removes the last excuse for a model to work from a scraped, mangled version.

Markdown-first also future-proofs you. HTML rendering fashions change; UTF-8 text with headings has outlived every one of them.

What not to do

The common failure modes, all observed in the wild:

• JavaScript-only content. If the text renders only after client-side execution, a large class of crawlers and fetchers sees an empty shell.
• Paywalled or login-walled quickstarts. Whatever is behind the wall does not exist in model answers; keep at least the evaluation path public.
• Screenshots of code and terminal output. Unreadable to the pipeline, uncopyable for humans, stale within months. Ship text with syntax highlighting instead.
• PDF-only documentation. Technically parseable, practically mangled: layout, code, and tables rarely survive.
• Aggressive bot-blocking without allowlists. Blanket rules written for scrapers routinely block the assistants your developers use; decide your crawler policy deliberately, as covered in measuring AI-driven adoption.
• Marketing prose inside reference pages. Models compress; make sure what survives compression is the instruction, not the adjectives.

A checklist to ship this quarter

1. Generate /llms.txt from your content source and link it in your footer.
2. Add /llms-full.txt or per-page Markdown endpoints, whichever your stack makes easy; both is better.
3. Rewrite the ten most-retrieved pages for self-containedness: descriptive headings, complete snippets, exact error strings.
4. Add transcripts or text equivalents for anything that currently lives only in video or images.
5. Run the assistant test on your top five integration questions and file a docs issue for every wrong answer.

None of this requires new tooling budget. It is editorial discipline applied with a new reader in mind, and it improves the docs for humans at every step - the same point agents are your new developers makes about the shift as a whole.

Related

• Agents are your new developers for why the machine reader now matters
• MCP servers are the new SDK for going beyond text into executable surfaces
• Measuring AI-driven adoption for knowing whether any of this works