# How I'm making our documentation agent-friendly (and how I'm not) **Date:** 2026-05-15 **Author:** Devin Logan **Source:** https://buildwithfern.com/post/agent-friendly-docs > Writing docs that AI agents can actually use means doing content work and relying on platform scaffolding. Here's what I do, and what I can't. --- It's one thing to use AI to write the docs; it's another thing to write docs that AI use. I'm the [sole technical writer at Fern](https://buildwithfern.com/post/ai-assisted-technical-writer), where I maintain documentation for [Fern Docs](https://buildwithfern.com/learn/docs/getting-started/overview) and [SDKs across nine languages](https://buildwithfern.com/learn/sdks/introduction/overview). Our docs are a contract with the customer—they're how current customers troubleshoot, new customers onboard, and prospects evaluate whether Fern is the right tool for them. My baseline assumption is that customers are accessing our docs primarily through agents, whether that's via [Ask Fern](https://buildwithfern.com/learn/docs/product-overview/ask-ai), a local tool like Claude Code or Cursor, or some other AI interface. This might be the first or only interaction people have with our docs, and I want it to be a good one. Writing well-structured docs for humans and [writing for agents](https://dacharycarey.com/2026/02/18/agent-friendly-docs/) aren't in tension, but they're not identical either. The other thing I've come to believe: the content work only matters because the platform surfaces it to agents. Content craft and platform scaffolding are interdependent, and I want to talk about both sides. Here's what I actually do, day to day, to make Fern's docs work for both audiences—and where the ceiling is for what I can do on the content side alone. ## Writing content AI can act on The biggest shift in my thinking hasn't been about keyword density or metadata (though those matter). It's about intent. When a developer asks an AI agent for help with Fern, the agent isn't browsing—it's trying to *do something*. The docs need to support that. ### Making flows executable, not just readable Our [docs quickstart](https://buildwithfern.com/learn/docs/getting-started/quickstart) is one of our most-read pages by both humans and LLMs. Roughly a third of visitors to that page are LLMs, and I expect that share to grow. The quickstart walks you through installing the CLI, initializing a docs project, configuring your org, and publishing. There's a guided UI option, but the entire flow can also run via CLI—which means an AI agent should be able to *execute* the quickstart, not just summarize it. My goal was to give an agent the page and say "create and publish a new docs site for me," and have it actually do it: prompting me for my org name and domain, running the commands, handling the configuration. To get there, I used `llms-only` tags to add context agents need but humans don't—more verbose content on file structure, what to expect after running each command, troubleshooting tips, how to deal with interactive commands. The human-facing page stays clean, and the agent gets the extra scaffolding to act autonomously. I iterated on this myself, running the entire flow multiple times with Claude Code and adding context wherever the agent got stuck, until everything worked and I got a new live docs site without having to run a single command myself. I've expanded this approach to our SDK quickstarts, and I'm looking at other pages next. Any flow that doesn't require a UI interaction is a candidate. ### Explaining systems, not just steps Not every agent-facing addition is procedural. Sometimes the thing an agent needs isn't a command or a fix—it's enough context to reason about the system it's working with. Our [Ask Fern overview](https://buildwithfern.com/learn/docs/ai-features/ask-fern/overview) has a short "Under the hood" section in `llms-only` tags—a numbered breakdown of how the RAG pipeline works (chunking, vector retrieval, RBAC filtering, keyword fallback) plus a sequence diagram. A customer enabling Ask Fern doesn't need any of that, and putting it on the page would make a straightforward feature feel like it requires understanding the internals to use. But an agent helping a developer figure out why their own Ask Fern surfaces some pages and not others would absolutely use that detail. `llms-only` keeps the page action-oriented for humans without giving up what the agent needs. It's a different shape from the quickstart pattern. The quickstart is "here's extra scaffolding so you can act." This is "here's extra context so you can reason." Both are content humans don't need but agents do. ### Stripping down pages for agents Our [docs overview page](https://buildwithfern.com/learn/docs/getting-started/overview) is styled for humans, and it should be: card groups, icons, dark/light mode variants, all wrapped in JSX. A landing page is exactly where design earns its keep—it sets the tone, signals what kind of product this is, and helps someone get their bearings. But an agent fetching that page gets a lot of component boilerplate, image references, and CSS class names wrapped around very little actual content. So for pages like this, agents now get a stripped-down markdown version with the same wayfinding links but without the styling. The human-facing page stays rich; the agent-facing version is clean. Our [homepage](https://buildwithfern.com/) is the extreme case. It's almost entirely Rive animations, custom JSX grids, and image variants for light and dark mode—there's barely any prose in the source at all. That's deliberate: a human landing on the site shouldn't be reading paragraphs, they should be feeling the product through motion and visual hierarchy, getting a sense of what Fern is and how its pieces fit together. An agent has the opposite need—it doesn't care about polish, it needs a clean list of where to go next. So I hide the entire human-facing block with `llms-ignore`, and a parallel `llms-only` block holds a clean markdown table of contents pointing to the same destinations. ### Keeping content scoped and current Long monolith pages hit token limits and make AI search retrieval harder—but they're not great for humans either. Breaking them into focused, self-contained pages is one of those changes where the AI motivation just accelerates a decision that was already right. Stale content, long the bane of a tech writer’s existence, is worse. A human might notice a page looks outdated and go looking for something more recent. An AI agent will confidently relay whatever it finds, even if the feature was deprecated six months ago. I actively remove or hide content that's stale or in early access—if a feature isn't ready for general use, the docs for it shouldn't be where Ask Fern can surface it as the answer to a customer question. ### **Making pages findable and parseable** Agents need enough context to decide whether to fetch a page at all, which section to look at, and where to find related content. Descriptions are how agents decide whether to fetch a page at all. Fern Docs has built-in support for frontmatter fields like `title`, `description`, and `subtitle`, and these flow directly into `llms.txt`. I've started treating frontmatter the way I'd treat a commit message—a clear, specific summary that helps someone (or something) decide if this is what they're looking for. Every markdown response also includes a short pointer at the top telling agents where to find the full docs index (`llms.txt`) and the expanded version with API and SDK content (`llms-full.txt`). I originally maintained that pointer by hand—a snippet inside `llms-only` tags that I pasted into every page. It was the right content decision, but it didn't scale. The platform now auto-prepends it to every markdown response. The other half of findability is keeping links stable once an agent has them. When I make a minor change to a page title—say, renaming "Quickstart" to "TypeScript quickstart"—I keep the URL slug the same. The old links still work. I save redirects for actual structural changes, like moving a page to a different section. ## How I'm *not* making our docs AI-friendly Agents don't access and consume docs like humans do. Everything above is content work, but none of it reaches an agent without [platform-level scaffolding](https://buildwithfern.com/post/agent-score). I can write perfect product descriptions for every page. But those descriptions only reach agents because Fern generates an `llms.txt` that indexes them. If the platform didn't do that, my descriptions would just be metadata sitting in frontmatter, invisible to any agent approaching the docs cold. I can break pages into focused, self-contained units. But that only helps AI search if the platform handles chunking, retrieval, and ranking well. A well-scoped page in a bad search index is still unfindable. I can add `llms-only` content to make flows executable, strip pages down to clean markdown, or keep system internals out of the way. But that tag only exists because the platform built it into its markdown content negotiation for agents. Without it, every one of those decisions collapses into a worse one: clutter the human page, or leave the agent without context. The reverse is also true. A platform that generates a beautiful `llms.txt` from empty frontmatter isn't helping anyone. A great chunking strategy over stale, monolithic content still retrieves stale, monolithic content. Platform scaffolding gives content work somewhere to land; content work gives platform scaffolding something worth surfacing. The most AI-friendly docs are the ones where both sides are working together—and if you want to see where yours stand, your [Agent Score](https://buildwithfern.com/agent-score) is a decent place to start.