{"slug": "how-to-make-your-developer-documentation-work-for-agents", "title": "How to Make Your Developer Documentation Work for Agents", "summary": "FusionAuth documentation engineer Nathan Contino reports that AI agents cannot yet produce consistently accurate documentation, so the company keeps long-form content, tutorials and release-note editing human-written while using agents only for tasks like updating redundant API field descriptions and auditing gaps between its API reference and OpenAPI spec. FusionAuth measured its docs site with the open-source command-line tool afdocs, scoring 97 out of 100 (grade A) on the Agent-Friendly Docs Scorecard as of August 25, 2026, after running `npx afdocs check https://fusionauth.io/docs --format scorecard`. Contino notes agents do not run JavaScript or usually send a user agent, so traditional analytics cannot measure agent traffic on documentation sites.", "body_md": "# How to Make Your Developer Documentation Work for Agents: Lessons from the Trenches\n\nBy Nathan Contino\n\n## On this page\n\nIncreasingly, 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?\n\n## Docs *for* Agents, not *by* Agents[#](#docs-for-agents-not-by-agents)\n\nAgents 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.\n\nTo 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.\n\n## So What *Do* Agents Want?[#](#so-what-do-agents-want)\n\nAI 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?\n\n### Metrics[#](#metrics)\n\nThe answer is metrics: find something objective to measure, and track it as you make changes.\n\nBefore 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.\n\nIn 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.\n\nFortunately, 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](https://www.afdocs.dev/) 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:\n\n``` bash\n$ npx afdocs check https://fusionauth.io/docs --format scorecard\n```\n\nWhen you run the report, you'll see output similar to the following:\n\n```\nRunning checks on fusionauth.io/docs...\n\nAgent-Friendly Docs Scorecard\n==============================\n\nhttps://fusionauth.io/docs · 8/25/2026, 2:52:38 PM\n\n  Overall Score: 97 / 100 (A)\n\n  Category Scores:\n    Content Discoverability              100 / 100 (A+)\n    Markdown Availability                100 / 100 (A+)\n    Page Size and Truncation Risk         85 / 100 (B)\n    Content Structure                    100 / 100 (A+)\n    URL Stability and Redirects          100 / 100 (A+)\n    Observability and Content Health      98 / 100 (A)\n    Authentication and Access             99 / 100 (A)\n\n  Check Results:\n\n    Content Discoverability\n      PASS  llms-txt-exists                llms.txt found at 2 locations; using https://fusionauth.io/docs/llms.txt as canonical\n      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\n            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.\n      PASS  llms-txt-size                  llms.txt is 962 characters (under 50,000 threshold)\n      PASS  llms-txt-links-resolve         All 12 same-origin links resolve (13 total links)\n      PASS  llms-txt-links-markdown        12/12 same-origin links point to markdown content (100%)\n      PASS  llms-txt-directive-html        llms.txt directive found in HTML of all 50 sampled pages, near the top of content\n      PASS  llms-txt-directive-md          llms.txt directive found in markdown of all 50 sampled pages, near the top of content\n\n    Markdown Availability\n      PASS  markdown-url-support           50/50 sampled pages support .md URLs (100%)\n      PASS  content-negotiation            50/50 sampled pages support content negotiation (100%)\n\n    Page Size and Truncation Risk\n      PASS  rendering-strategy             All 50 sampled pages contain server-rendered content\n      FAIL  page-size-markdown             1 of 50 pages exceed 100K chars (max 506K)\n            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.\n      FAIL  page-size-html                 5 of 50 sampled pages convert to over 100K chars (max 1355K HTML → 571K markdown (63% boilerplate))\n            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.\n      PASS  content-start-position         Content starts within first 10% on all 50 sampled pages (median 1%)\n\n    Content Structure\n      PASS  tabbed-content-serialization   No tabbed content detected across 50 sampled pages\n      PASS  section-header-quality         No tabbed content found; header quality check not applicable\n      PASS  markdown-code-fence-validity   All 281 code fences properly closed across 52 pages\n\n    URL Stability and Redirects\n      PASS  http-status-codes              All 50 sampled pages return proper error codes for bad URLs\n      PASS  redirect-behavior              All 1 redirect(s) across 50 sampled pages are same-host HTTP redirects\n\n    Observability and Content Health\n      PASS  llms-txt-coverage              llms.txt covers 100% of 722 sitemap doc pages\n      WARN  markdown-content-parity        8 of 50 pages have minor content differences between markdown and HTML\n            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).\n      PASS  cache-header-hygiene           All 52 endpoints have appropriate cache headers\n\n    Authentication and Access\n      WARN  auth-gate-detection            1 of 50 sampled pages require authentication (49 accessible)\n            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.\n      PASS  auth-alternative-access        Alternative access detected (public-llms-txt, public-markdown, partial-public-access) for site with 1 auth-gated pages\n\nFull spec: https://agentdocsspec.com/spec/\n```\n\nThis metric measures a few important aspects of our AI strategy:\n\n- **Content discoverability** : our site should include an`llms.txt` index that helps agents explore the site -- the machine equivalent of a navigation sidebar\n- **Markdown availability** : HTML pages are styled for human consumption; agents (and some humans) prefer token-lean Markdown alternatives\n- **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\n- **Content structure** : ensure that links, code blocks, images, and other non-prose page contents are well-formatted and follow web accessibility standards\n\nAFDocs 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](https://better-static-sites.github.io/build-tools/gen-markdown-pages/) 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](https://better-static-sites.github.io/build-tools/mermaid/) that generates SVGs at build time and an ['On this page' widget](https://better-static-sites.github.io/layout/toc/) also built from the site's AST.\n\nOur 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.\n\nOnce 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.\n\n## Process Improvements[#](#process-improvements)\n\nWhile 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.\n\nHere 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.\n\nThat's why we've recently optimized our build to decrease wait times and bottlenecks. So far, we:\n\n- pruned unnecessary dependencies.\n- moved away from slow dependencies and actions, like our old link checkers, and in some cases [rewrote them for speed](https://github.com/nathan-contino/astro-link-checker) .\n- deleted unused and unnecessary images.\n- parallelized our deploy uploads. Deploy times dropped from 7 minutes to 2 minutes, and our build times decreased by over 50%.\n- added checks at build time to catch broken links, badly formatted Markdown, and more.\n- added checks for the validity of external links in files changed by a PR.\n- added weekly automations that check external links and for links to closed GitHub Issues in the entire repository.\n- 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.\n- removed unreliable or confusing checks that routinely broke and slowed down development.\n\nAnd 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!\n\n## The Future[#](#the-future)\n\nNobody 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!).\n\nOne 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:\n\n- listening to feedback about where people get stuck.\n- keeping an eye on our site search and 'Chat with AI' widget to identify gaps.\n- breaking up large, confusing pages into smaller chunks.\n- monitoring and adding new metrics to understand our audiences (meat *and* silicon)\n\n...and of course, coming up with new content every day to help people accomplish things they haven't even thought of yet with FusionAuth.\n\nRelated\n\n[Extendapi](https://fusionauth.io/docs/extend/examples/api-gateways/)\n\nHow to use an API gateway with a FusionAuth token.\n\n[Get Startedapi](https://fusionauth.io/docs/get-started/use-cases/authorization-hub)\n\nIntegrate with third party platforms, using FusionAuth to safely store refresh tokens.\n\n[Aiaiai agent identityapi](https://fusionauth.io/articles/ai/mcp-connecting-software-ai)\n\nLearn how the Model Context Protocol (MCP) standardizes AI agent-to-software communication and why OAuth-based authentication is essential for secure, scalable implementations.\n\n[Aiaiai agent identity](https://fusionauth.io/articles/ai/ai-agent-identity-overview)\n\nLearn how to secure your applications as AI agents become first-class actors alongside humans in your systems.", "url": "https://wpnews.pro/news/how-to-make-your-developer-documentation-work-for-agents", "canonical_source": "https://fusionauth.io/articles/ai/llms-for-docs", "published_at": "2026-10-07 19:24:56+00:00", "updated_at": "2026-10-07 19:49:56.679757+00:00", "lang": "en", "topics": ["ai-agents", "ai-crawlers", "developer-tools", "ai-tools"], "entities": ["FusionAuth", "Nathan Contino", "afdocs", "OpenAPI", "Astro", "GitHub Actions", "Google Analytics"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/how-to-make-your-developer-documentation-work-for-agents", "markdown": "https://wpnews.pro/news/how-to-make-your-developer-documentation-work-for-agents.md", "text": "https://wpnews.pro/news/how-to-make-your-developer-documentation-work-for-agents.txt", "jsonld": "https://wpnews.pro/news/how-to-make-your-developer-documentation-work-for-agents.jsonld"}}