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, where I maintain documentation for Fern Docs and SDKs across nine languages. 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, 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 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 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 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 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 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.
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 is a decent place to start.