# Documentation Is Dual-Audience Infrastructure ## Claim Reference documentation now serves machines as well as people, so the format it is published in is a cost imposed on every reader's compute bill rather than a presentation choice. <!-- atomicity: 1 idea ✓ --> ## Evidence **Source**: [[3. Resources/Readwise/Articles/Drupal AI Learners Club - 2026-07-31 - Getting AI to Read Your Docs With Jurgen Haas]] Haas tokenized one question — which fields the Drupal core send-email action uses — against the same documentation served three ways: | Path | Tokens | |---|---| | Agent scrapes the PHP source | 600,000+ | | Agent scrapes the rendered HTML of one page | 154,000 | | Agent reads the source markdown | **161** | The HTML figure is not incidental and it is what makes this generalizable: MkDocs embeds the full site navigation into **every** rendered page, so an agent asking about one plugin pays for the table of contents of 1,364 pages. Any generator that renders navigation per-page has the same property. The part that makes this actionable rather than merely alarming is that the first fix requires no engineering. MkDocs already serves the source markdown if a URL is suffixed with `index.md`. Three orders of magnitude, available immediately, on infrastructure already deployed. And the traffic asks the question the other way round. Over six months the ECA Guide received roughly 11,000 unique human visits and 244,000 machine visits. Haas caveats it himself — crawler traffic is not excluded — but even heavily discounted, the machine audience is not a rounding error. ## Scope & conditions - **Holds** for *reference* material with structured, enumerable content — API surfaces, plugin catalogs, configuration schemas — where an agent needs one precise fact and everything else on the page is overhead. - **Breaks** for narrative or conceptual documentation, where the surrounding context an agent would strip is the actual value. A tutorial is not improved by being served as a fact table. - **Weakens** if agent tooling standardizes on stripping boilerplate before billing, which would close most of the HTML gap without any publisher action. Haas notes some agents already do this, inconsistently and at a cost. - **Does not follow** that documentation should be written for machines. The claim is about the *format it is served in*, not the prose. The same markdown serves both audiences; only the wrapper differs. ## Links - [[3. Resources/Permanent Notes/A Declared Capability Costs You Every Turn Not Every Use]] — because extends: the sibling finding from the same source. Both are token costs that stay invisible until measured — one in how documentation is served, one in how tools are declared. - [[3. Resources/Permanent Notes/When Answers Are Cheap Understanding Becomes the Scarce Good]] — because extends: if retrieval is cheap and abundant, the differentiated value of documentation is accuracy and structure rather than availability. - [[3. Resources/Permanent Notes/Vague Prompts Are Expensive Specificity Cuts AI Error and Cost Together]] — because extends: both locate an avoidable token cost above the model layer, one at the request and one at the source. - [[3. Resources/Permanent Notes/The Design File as a Programmable Bidirectional Surface for Agents]] — because extends: the same argument applied to design artifacts rather than prose — an open, structured data model is what makes deep agent access possible at all. - [[3. Resources/Permanent Notes/Real Standards Adoption Means Implementing the Draft and Pushing the Gaps Upstream]] — because applies-in: agent resource discovery (`ai-catalog.json`) is an emerging convention where adopting and feeding gaps upstream is the contribution. - [[3. Resources/Permanent Notes/Fluency Makes Small Errors Harder to Catch Than Large Ones]] — because contrasts: cheap accurate retrieval is the counterweight to plausible generation; an agent that can look it up does not have to guess it. - [[Personal Knowledge Management MOC]] — because applies-in. - [[AI Cost & Tokenomics MOC]] — because applies-in. - [[3. Resources/MOCs/Documentation & Technical Writing MOC]] — applies-in: the docs discipline map; the "docs as product and infrastructure" cluster starts from this claim - [[3. Resources/Permanent Notes/Serving Clean Markdown Solves Retrieval but Not Discovery]] — extended by: serving markdown by path doesn't tell an agent which page answers its question (Sepic). - [[3. Resources/Permanent Notes/A Coding Agent Evaluates a Tool by Reading Its Docs and Pricing Pages]] — extended by: setup page, README and pricing text are the product the agent evaluates (Silverman and Barnes). - [[3. Resources/Permanent Notes/Developers Who Build Through Agents Often Can't Name the API They Call]] — applied in: start support from what the developer is building, not which API they call (Rabasa). ## Implications - The immediate audit is one question per documentation site: does it already serve source markdown at a predictable URL? If yes, publicize it. If no, that is the cheapest large win available. - Generating reference documentation from source has a second benefit beyond effort saved — **no drift**, because extending functionality updates the docs in the same commit. Human commentary survives regeneration through include files rather than hand-editing generated pages. - Analytics that conflate human and machine traffic will misreport who documentation is for. Separating them is prerequisite to reasoning about it. - A single `ai-catalog.json` at a well-known path is a one-file step toward agents finding authoritative information instead of scraping or guessing. ## Open Questions - Does the 21:1 machine-to-human ratio survive excluding general-purpose crawlers? Haas explicitly did not correct for them, and the corrected figure is the one that matters. - Is the per-page navigation cost specific to MkDocs, or do Sphinx, Docusaurus, and Hugo share it? The mechanism suggests they do; nobody has measured across generators. - If publishers optimize for machine readers, does human documentation quality suffer, improve, or stay untouched? - Does the drift-freedom claim hold for the hand-written portion? Generated reference cannot drift; the conceptual pages around it still can. ## Source - [[3. Resources/Readwise/Articles/Drupal AI Learners Club - 2026-07-31 - Getting AI to Read Your Docs With Jurgen Haas]] — the three-way token measurement, the navigation-per-page mechanism, and the traffic figures