How to Make Your Developer Documentation Work for Agents: Lessons from the Trenches

Increasingly, developers turn to AI chatbots and other LLM-powered assistants for tasks like programming and research. To understand how to use a library or piece of software, those agents need a user manual. But when things get tricky (or when developers want to flex their programming muscles), humans still read the docs. Now documentation has two audiences: humans and agents. So how do we build the best documentation for both?

Docs for Agents, not by Agents#

Agents can do many things. Unfortunately, they do not yet produce consistently true documentation that is pleasant for humans to read or easy to navigate. That's why we have a dedicated documentation writer/engineer (that's me!) who gives our docs a human touch. Here at FusionAuth, we lean on agents to help with the tedious parts of our documentation -- updating redundant API field descriptions, auditing the gaps between our API reference and our OpenAPI spec, debugging arcane Astro errors, and writing GitHub Action glue code. But our long-form content, our tutorials, and even the editing of shorter content like our release notes is all human. We've experimented plenty with agent-written documentation, and it consistently requires more validation and rewriting than it would take to write the content from scratch ourselves. So we write it from scratch, ourselves.

To put it like an agent would: it's not about documentation output, it's about the load-bearing polish of quality, correctness, and brevity that only a brain can provide. Not just a human in the loop -- it's a human at the wheel.

So What Do Agents Want?#

AI best practices are a moving target. In the industry, in your organization, in professional circles, probably even in your friend group, there are many (contradicting) opinions. Some of them are probably even correct. So how do you know what recommendations to follow, and which to ignore?

Metrics#

The answer is metrics: find something objective to measure, and track it as you make changes.

Before we start on any major project, we like to define our metrics of success. In the software world, this is often performance or usability scores. Or you might aim for feature parity with another project.

In the world of documentation, metrics are both easy and hard. On one hand, with logging and tools like Google Analytics, we can keep track of user activity on the docs site. On the other hand, it's very difficult to tell the quality of a visit: did a user open a page, find an answer, and leave? Or did they lose interest because the page was too long? Agents don't provide any of these traditional metrics since they don't run JavaScript on the page, which means you don't get any of the usual analytics data about agents. They often don't even provide a user agent. In most cases, the only way to detect agent traffic is to track the number of requests made to your site that aren't captured by your traditional analytics, a number that likely also includes every person who chooses to block your analytics for privacy.

Fortunately, we don't have to track usage metrics to know how to make a site that agents can easily navigate. Instead, we used an open-source tool called afdocs to check a few key metrics for our site. Because this tool is open source and runs on the command line, you can locally run the very same metric that we use:

$ npx afdocs check https://fusionauth.io/docs --format scorecard

When you run the report, you'll see output similar to the following:

Running checks on fusionauth.io/docs...

Agent-Friendly Docs Scorecard
==============================

https://fusionauth.io/docs · 8/25/2026, 2:52:38 PM

  Overall Score: 97 / 100 (A)

  Category Scores:
    Content Discoverability              100 / 100 (A+)
    Markdown Availability                100 / 100 (A+)
    Page Size and Truncation Risk         85 / 100 (B)
    Content Structure                    100 / 100 (A+)
    URL Stability and Redirects          100 / 100 (A+)
    Observability and Content Health      98 / 100 (A)
    Authentication and Access             99 / 100 (A)

  Check Results:

    Content Discoverability
      PASS  llms-txt-exists                llms.txt found at 2 locations; using https://fusionauth.io/docs/llms.txt as canonical
      WARN  llms-txt-valid                 llms.txt contains parseable links but doesn't fully follow the proposed structure: https://fusionauth.io/docs/llms.txt: No heading-delimited sections found
            Fix: Your llms.txt contains parseable links but doesn't follow the standard structure. Add an H1 title as the first line and a blockquote summary (lines starting with >) to improve agent parsing.
      PASS  llms-txt-size                  llms.txt is 962 characters (under 50,000 threshold)
      PASS  llms-txt-links-resolve         All 12 same-origin links resolve (13 total links)
      PASS  llms-txt-links-markdown        12/12 same-origin links point to markdown content (100%)
      PASS  llms-txt-directive-html        llms.txt directive found in HTML of all 50 sampled pages, near the top of content
      PASS  llms-txt-directive-md          llms.txt directive found in markdown of all 50 sampled pages, near the top of content

    Markdown Availability
      PASS  markdown-url-support           50/50 sampled pages support .md URLs (100%)
      PASS  content-negotiation            50/50 sampled pages support content negotiation (100%)

    Page Size and Truncation Risk
      PASS  rendering-strategy             All 50 sampled pages contain server-rendered content
      FAIL  page-size-markdown             1 of 50 pages exceed 100K chars (max 506K)
            Fix: 1 of 50 markdown pages exceed 100K characters and will be truncated by agents. Break these into smaller pages or restructure serialized tabbed content.
      FAIL  page-size-html                 5 of 50 sampled pages convert to over 100K chars (max 1355K HTML → 571K markdown (63% boilerplate))
            Fix: 5 of 50 pages convert to over 100K characters of markdown. Break large pages into smaller units, reduce navigation boilerplate, or provide markdown versions that bypass the HTML conversion overhead.
      PASS  content-start-position         Content starts within first 10% on all 50 sampled pages (median 1%)

    Content Structure
      PASS  tabbed-content-serialization   No tabbed content detected across 50 sampled pages
      PASS  section-header-quality         No tabbed content found; header quality check not applicable
      PASS  markdown-code-fence-validity   All 281 code fences properly closed across 52 pages

    URL Stability and Redirects
      PASS  http-status-codes              All 50 sampled pages return proper error codes for bad URLs
      PASS  redirect-behavior              All 1 redirect(s) across 50 sampled pages are same-host HTTP redirects

    Observability and Content Health
      PASS  llms-txt-coverage              llms.txt covers 100% of 722 sitemap doc pages
      WARN  markdown-content-parity        8 of 50 pages have minor content differences between markdown and HTML
            Fix: 8 pages have minor content differences between their markdown and HTML versions. If this is intentional audience segmentation, adjust --parity-pass-threshold and --parity-warn-threshold (set both to 0 for informational mode).
      PASS  cache-header-hygiene           All 52 endpoints have appropriate cache headers

    Authentication and Access
      WARN  auth-gate-detection            1 of 50 sampled pages require authentication (49 accessible)
            Fix: Some documentation pages require authentication while others are public. Agents can access public pages but will fall back on training data for gated content. Consider ungating reference docs and API guides.
      PASS  auth-alternative-access        Alternative access detected (public-llms-txt, public-markdown, partial-public-access) for site with 1 auth-gated pages

Full spec: https://agentdocsspec.com/spec/

This metric measures a few important aspects of our AI strategy:

• Content discoverability: our site should include an llms.txt index that helps agents explore the site -- the machine equivalent of a navigation sidebar
• Markdown availability: HTML pages are styled for human consumption; agents (and some humans) prefer token-lean Markdown alternatives
• Page size and truncation risk: if nobody has optimized your page size in human memory, you can probably cut out a lot of cruft, even in a static site
• Content structure: ensure that links, code blocks, images, and other non-prose page contents are well-formatted and follow web accessibility standards

AFDocs was a great starting point for us: we originally got an F. So we made some improvements to our documentation infrastructure. After adding an Astro plugin to generate Markdown from the built-time AST and automating the production of llms.txt indexes, we focused on discoverability: we added links to the Markdown version of each page and the llms.txt index, as well as a redirect for any request that passes the accept/markdown header. Then we focused on accessibility, optimizing our page sizes, reducing boilerplate, lifting content towards the top of the HTML, and displaying diagrams as their mermaid declarations in our Markdown output and alt text. We removed all unnecessary JavaScript from our documentation pages, moving to a lean mermaid rendering plugin that generates SVGs at build time and an 'On this page' widget also built from the site's AST.

Our documentation has a long history, so we had a lot of work to do cleaning it up. But we're finally starting to see returns on all of this cleanup work, as we hit fewer and fewer 'gotchas' every release.

Once we maxed out those scores, we turned to more advanced metrics: an internal agent benchmark that demonstrates how FusionAuth measures up against the competition when used to accomplish basic auth tasks like adding a login, enabling SSO, and more. Those metrics are becoming a form of CI/CD check for us now: as new versions of agents debut and we release new features, we need to track our site's performance and figure out where users are getting stuck.

Process Improvements#

While our process improvements don't directly help agents accessing the docs from the web, they do help our documentation team keep up with the increased pace of modern development.

Here at FusionAuth, we have a small team. We only have one dedicated documentation writer. So it doesn't make sense to waste documentation time on anything that we can automate. In a world where developers are moving faster than ever with agents, we have to keep up.

That's why we've recently optimized our build to decrease wait times and bottlenecks. So far, we:

• pruned unnecessary dependencies.
• moved away from slow dependencies and actions, like our old link checkers, and in some cases rewrote them for speed.
• deleted unused and unnecessary images.
• parallelized our deploy uploads. Deploy times dropped from 7 minutes to 2 minutes, and our build times decreased by over 50%.
• added checks at build time to catch broken links, badly formatted Markdown, and more.
• added checks for the validity of external links in files changed by a PR.
• added weekly automations that check external links and for links to closed GitHub Issues in the entire repository.
• created test suites for QuickStarts and our larger examples, which we produce code blocks directly from at build time and publish directly to GitHub as repositories to preserve a single source of truth and reduce copy/paste errors.
• removed unreliable or confusing checks that routinely broke and slowed down development.

And most importantly, we introduced hosted preview builds, so everyone working on a PR can view the rendered changes to the site, live, instead of checking out a branch locally and running a build. Thanks to some clever optimizations, our preview builds take just 90 seconds -- almost as fast as a full site build on your local machine!

The Future#

Nobody knows what the future holds for agentic development. Maybe the chickens will finally come home to roost, prices will skyrocket, and we'll settle at a happy medium of hybrid human-agent development. Maybe we'll all be sipping piña coladas on the beach in a couple of years and the agents will do all the software development and docs-reading themselves. Maybe agents will finally even learn how to write gooder (I hope not!).

One thing is certain: to have great documentation, you need to meet your users where they're at. Many of our users are now agents, so we've made improvements to our docs to accommodate them. But even more of our users are, and hopefully will remain, human. So we need to make great docs for both audiences. That means:

• listening to feedback about where people get stuck.
• keeping an eye on our site search and 'Chat with AI' widget to identify gaps.
• breaking up large, confusing pages into smaller chunks.
• monitoring and adding new metrics to understand our audiences (meat and silicon)

...and of course, coming up with new content every day to help people accomplish things they haven't even thought of yet with FusionAuth.