Documenting APIs: New Era, Same Craft - Javier Rubio  🔗 **Source:** [Documenting APIs: New Era, Same Craft - Javier Rubio](https://www.youtube.com/watch?v=PM9Kkfs6Ea0) > [!note]+ Document Notes > tags: [api-documentation, openapi, arazzo, docs-as-code, diataxis, ai-agent-consumers] > author: Javier Rubio > source: Write the Docs (YouTube) > reference: https://www.youtube.com/watch?v=PM9Kkfs6Ea0 > date created: 2026-09-23 10:28 > > > [!info] Generated analysis — not the author's words. Sections below are machine-written > > from the captured source. Only text inside `> [!quote]` blocks is verbatim from the author. > > Do not quote or attribute any other line to the named author. > > # 🏷️ Title: Documenting APIs: new era, same craft - Javier Rubio > <!-- deep-read:sections start --> ## 🧭 Table of contents - [📝 Summary](#-summary) - [📖 Main content](#-main-content) - [🗒️ Notes](#️-notes) - [📚 References](#-references) - [🗣️ Paraphrase](#️-paraphrase) - [📰 Newsletter](#-newsletter) - [✅ Action items](#-action-items) - [🧪 Hypotheses](#-hypotheses) - [📊 Methodology](#-methodology) - [❓ Questions](#-questions) - [🔮 Future research](#-future-research) - [💡 Implications](#-implications) - [🧠 Learning styles assessment](#-learning-styles-assessment) - [📊 Accessibility assessment](#-accessibility-assessment) - [🌍 DEIB assessment](#-deib-assessment) - [✅ Logical validity](#-logical-validity) - [🛡️ DARVO analysis](#️-darvo-analysis) - [🎯 Conclusion](#-conclusion) - [🔄 Refactor appendix](#-refactor-appendix--documenting-apis-new-era-same-craft---javier-rubio) ## 📝 Summary - **What happened.** Write the Docs published Javier Rubio's 34:45 conference talk from Write the Docs Berlin 2026 on 2026-09-22. The talk runs about 28 minutes and is followed by a 6-minute Q&A with the session host, who is introduced as Abby. There are no chapters. The auto-captions garble almost every product and standard name: "Arato" for Arazzo, "whistle file" for WSDL, "beta store" for Petstore, "docuous" for Docusaurus, "Daniel proa" and "taxis" for Daniel Procida and Diátaxis, "cloer" for Cloudflare, "mainly" for what is almost certainly Mintlify, "CLA" for CLI, and "dogs" for docs. Quotes below preserve the transcript spelling. - **The claim.** Three "insights," in the speaker's own framing. First, for REST APIs, which have no typed contract, the documentation is the contract (00:03:03). Second, the closer the OpenAPI spec is generated to the code, the lower the maintenance cost and the easier shared ownership becomes, with automated tests that turn CI red when the API changes as the recommended route (00:11:14, 00:14:50). Third, the API is a product and the docs are the API's interface, so no marketing claim can sell an API, only docs can (00:22:15, 00:28:10). - **The standards covered.** SOAP/WSDL, REST, GraphQL, and a fourth RPC-style protocol the captions lose (likely gRPC); Swagger/OpenAPI; OpenAPI's late webhook support and its JSON Schema subset/superset confusion; vendor `x-` extensions; and three gap-fillers: Arazzo (workflows across calls), AsyncAPI (event-driven APIs), and Overlays (translations, defaults, config layered on a spec). - **The conventions the standards don't cover.** Authentication, error handling, pagination, rate limiting, and versioning are named at 00:04:31 as the guides you must write by hand because neither REST nor OpenAPI standardizes them. Later additions: sandbox limitations and test data, a published versioning policy with an advance-warning window, migration guides, and a changelog. - **The AI-era section.** Rubio cites a Cloudflare blog for "more than 50%" of internet traffic being non-human and a sponsor's open-source benchmark for "more than 66%" of docs traffic in July being AI (00:25:14). Both numbers are relayed, not shown. He argues AI readers value predictability like developers do, that companies ship CLIs rather than MCP servers because MCPs consume more tokens (00:25:57), and that publishing Markdown plus an `llms.txt` file cuts AI crawl overhead (00:26:40). On AI writing specs: big-bang generation is unreviewable; use AI to write the tests that generate the spec instead (00:16:20, 00:17:05). - **Why it matters.** For anyone documenting a REST API that ships without a typed contract, the talk gives a ranked list of five places a spec can come from (hand-written, traffic capture, annotations, tests, framework introspection) and a single test for whether the pipeline is trustworthy: does CI go red when the API changes and the docs don't? - **Key stakeholders.** Technical writers and API engineers sharing spec ownership; the OpenAPI Initiative (OpenAPI, Arazzo, Overlays); the AsyncAPI Initiative; Daniel Procida and the Diátaxis framework; Write the Docs sponsors whose tools are pointed to but mostly unnamed; and the new non-human readers, agents and coding assistants consuming docs through MCP servers, CLIs, and `llms.txt`. - **Risks and tradeoffs.** The strongest recommendations rest on the speaker's experience at one employer (a tax-compliance SaaS the captions render as "quadro," likely Quaderno) and one 2023 tooling survey he calls obsolete. The 50% and 66% figures arrive without links, dates, or methodology. The "MCPs consume a lot of tokens" claim is stated as observation, not measured. The Q&A admits there's no easy answer to team shrinkage from AI. - **Bottom line.** The craft argument is sound and carries mechanisms: a spec generated by tests fails visibly, a hand-written one drifts silently. The AI-era numbers are hearsay in this source and should be traced before reuse. The Arazzo, Overlays, and `llms.txt` pointers are the concrete things to go read next. ## 📖 Main content **The historical setup.** Rubio opens with 30 years of API protocols (00:01:32 to 00:03:03). SOAP was strictly typed: a WSDL file defined every parameter, the XML was verbose and hard for humans to read, but you could generate client code from it. REST arrived after the dot-com bubble and became the default around 2005 when front-end mashups started mixing data from several APIs. REST has no contract. That's its flexibility and its cost: it's easy to start and it needs documentation to be usable. GraphQL brought a schema back but with a hard caching story and a steep learning curve. A fourth protocol for internal remote procedure calls is mentioned but the captions destroy the name; gRPC fits the description. The conclusion he draws is the first of three "insights": for REST, the contract is the documentation. **Swagger as a substitute contract.** The Petstore example (captioned "beta store") gets a laugh at 00:03:47 because everyone in the room has seen it. Swagger, later OpenAPI, standardized describing an API in JSON or YAML, with YAML as the human-writable form, and shipped a UI that rendered the reference. It looked like the whole solution but wasn't. At 00:04:31 Rubio lists what neither REST nor OpenAPI standardizes: authentication, error handling, pagination, rate limiting, versioning. Those become the first guides you write by hand, and the description for the video lists them as a headline topic. **The fragmented ecosystem.** From 00:05:18: webhooks were poorly supported until recent OpenAPI versions (established: OpenAPI 3.1, released 2021, added the top-level `webhooks` object). The OpenAPI schema object was a subset of JSON Schema in some respects and a superset in others, so tools treated them interchangeably and broke on subtleties (established: 3.1 aligned with JSON Schema 2020-12 to end this). Vendors filled gaps with proprietary `x-` extensions. Three newer standards fill remaining gaps: Arazzo, whose name Rubio says is Italian for a woven wall hanging because it weaves the workflow of several API calls; AsyncAPI for event-driven APIs; and Overlays, which layer translations, configuration, or defaults over a spec. (Established: the OpenAPI Initiative published Arazzo 1.0 in May 2024 and Overlay 1.0 in October 2024.) **Conway's law applied to tooling.** At 00:06:49 he invokes Conway's law, dating it to 1970 or 1967 (the paper appeared in 1968, written in 1967), to argue that a fragmented standards ecosystem produces a fragmented tools ecosystem. The openapi.tools directory used to be a mess and has improved since gaining a sponsor and, in his reading, a technical writer. Postman started as a testing client and now documents APIs; Insomnia was the alternative, is "now another monster," and its founder is building a smaller open-source tool after selling. Three Write the Docs sponsors deal with API docs; he doesn't name them in the audio. His position: there's no silver bullet (captioned "silver valid"). Tools are either laser-focused or do-it-all, and neither is complete for a given team. Expensive monthly subscriptions relative to other SaaS are, to him, a signal that the problem is hard. This is an inference, not a measurement. **Map needs first, then model your tools.** At 00:09:46 he shows a 2023 tooling comparison from his last employer and calls it obsolete already. The advice is to inventory your engineering and writing workflows, then pick tools that fit them, not the reverse, and to consider the do-it-yourself route where you can shape open-source tools to your workflow. The worked example (00:10:29 to 00:11:14) is a tax-compliance SaaS that chose Docusaurus (Meta's docs framework, captioned "docuous"), which doesn't support OpenAPI natively, plus Redocusaurus (captioned "redocusarus"), a plugin that renders the Redoc React component inside the site. **Engineering lens: closer to the code.** The second insight, at 00:11:14: the closer spec generation sits to the code, the lower the maintenance toll and the easier shared ownership between engineers and writers. Docs-as-code treats the shipped code as source of truth; the aspiration is that docs deploy automatically whenever the API changes. He then ranks five sources for a spec (00:12:40 to 00:15:33): 1. **Hand-written.** The old route. Linters help. Usually owned by technical writers, which creates a knowledge silo. 2. **Traffic capture.** A proxy watches real API calls and infers the spec. Someone has to own and maintain that automation pipeline. In Q&A (00:30:22) he clarifies this works like functional or integration tests driving the API, with the OpenAPI document as the output. 3. **Annotations.** Metadata in the code, in the repo, updated in the same commits. Easier to update but still a manual step; nothing fails when you forget. 4. **Automated tests.** Tests are code, tests run, and tests go red. This is the route his team took, with a Ruby gem that generates the spec from request specs (the gem isn't named; rswag matches the description). The condition at 00:14:50: the tests must fail when the API changes, otherwise a separate test suite is just another hand-written spec. 5. **Framework introspection.** The code is the spec. Named examples: .NET since version 9 (established: ASP.NET Core 9 ships built-in OpenAPI document generation) and FastAPI for Python (established: FastAPI generates OpenAPI from type hints). No tests needed. **Where AI helps and where it doesn't.** At 00:15:33 he answers a round-table question from the previous day. Generating a whole spec with AI in one pass is dangerous because nobody can review a large YAML or JSON file and catch a hallucinated parameter. AI helps with maintenance: a specialized agent on pull requests flagging that the spec wasn't updated. It helps at low risk on traffic capture (parameter names, routes) and on annotations, but CI never goes red in those routes so misses stay hidden. With tests, misses show. His preference, stated as personal experience at 00:17:05, is to have AI write the tests that generate the spec rather than the spec itself. On framework introspection he's blunt at 00:17:50: code generation has been deterministic for decades and the same prompt to the same model yields different outputs, so AI "makes no sense" there. **Product lens.** The third insight, from 00:18:34: your API is a product (he treats this as industry consensus) so your docs are a product too. Map user personas by talking to them; a corporate integrator and a solo developer have different deadlines and emotions. His tip: help a few customers integrate for free and learn where the API hurts. Developers value predictability, so (00:20:47) provide a sandbox and document its limits, its test data, and how to simulate errors you'd otherwise only hit in production, like a failed payment. Publish a versioning policy, commit to a warning window for breaking changes ("one month in advance" is his example), ship migration guides, keep a changelog. The changelog also helps AI readers. The commercial stake at 00:22:15: CTOs can veto an API purchase, and docs are what they evaluate. **Diátaxis and Arazzo for guides.** He recommends Daniel Procida's Diátaxis (00:22:15 to 00:24:28), crediting Procida as technical lead at Canonical: four quadrants split by what the user does versus what the user knows, and by acquiring skill versus applying it, giving tutorials, how-to guides, reference, and explanation. He also borrows Diátaxis's organism metaphor: a small docs set is complete as it is and grows. Arazzo fits the how-to quadrant because it describes multi-call workflows rather than single endpoints, and, he adds, it stops AI from guessing how calls chain. **The new readers.** At 00:25:14 he relays two numbers: a Cloudflare blog saying more than 50% of internet traffic is non-human, and a sponsor's open-source benchmark saying more than 66% of docs traffic in July was AI. Neither is linked in the transcript. New use cases: autonomous agents integrating your API, and humans prompting an assistant to do it. New interfaces: MCP servers and CLIs. He claims companies with resources ship CLIs because MCPs consume many tokens, citing GitHub's CLI (captioned "GitHub GX CLA"). From a second sponsor benchmark (00:26:40): AI crawlers misread HTML, so publishing Markdown plus an `llms.txt` file (captioned "the LLMs," described as the robots.txt equivalent for machines) reduces token overhead. He ties this to data-center energy and climate at 00:27:25, in a hyperbolic aside. **Q&A.** Human-centric APIs: keep the product lens, software is about people (00:29:40). Traffic capture confusion: a proxy sits in the middle; it's an automation someone must own (00:30:22). Future of API docs: better collaboration tooling, but teams are shrinking because of AI, "one with AI" as a team, and an identity crisis for programmers and writers, with translators hit first (00:31:50 to 00:32:34). Getting developers to own the spec: automated tests that block merge, explicit team conventions, leading by example (00:33:17 to 00:34:02). **Contested or unverifiable in this source.** The 50% and 66% figures; the token-cost comparison between MCP and CLI; the claim that expensive tooling signals problem difficulty; and "teams are smaller than ever because of AI." Each is plausible and each arrives as assertion or anecdote. ## 🗒️ Notes #### ⏱️ [00:00:02](https://www.youtube.com/watch?v=PM9Kkfs6Ea0&t=2) Host introduction - The host frames the conference's running theme as "API as of AI" and says API documentation is "its own thing" with its own conventions, practices, and user needs. - She withholds the "most important component" as a teaser; the talk's answer is the docs themselves as the API's interface (00:28:10). #### ⏱️ [00:00:47](https://www.youtube.com/watch?v=PM9Kkfs6Ea0&t=47) Thirty years of API history - SOAP: strictly typed, WSDL contract (captioned "whistle file"), verbose XML, client code generation possible. - REST: post dot-com bubble, mainstream by about 2005 via front-end mashups; no contract, so flexible but dependent on documentation. - GraphQL: schema contract from "some big tech giant," hard caching, steep learning curve. A fourth RPC protocol is named but the captions lose it; gRPC fits. > [!quote] [00:03:03] > So the first insight of my talk will be the contract are the docs on some of these APIs. #### ⏱️ [00:03:47](https://www.youtube.com/watch?v=PM9Kkfs6Ea0&t=227) Swagger, Petstore, and what OpenAPI doesn't standardize - The Petstore example (captioned "beta store") is the room's shared reference. Swagger added a UI and standardized description in JSON or YAML, YAML being the more human-writable. - OpenAPI acts as a substitute contract for an untyped API but leaves five conventions to hand-written guides. > [!quote] [00:04:31] > neither rest or the contract by the documentation which is open API standardize any of authentication error handling pagenation rate limiting versioning #### ⏱️ [00:05:18](https://www.youtube.com/watch?v=PM9Kkfs6Ea0&t=318) The OpenAPI ecosystem and its gap-fillers - Webhooks poorly supported until recent versions. OpenAPI schema was a subset of JSON Schema in some ways and a superset in others, so tools that treated them as interchangeable broke on subtleties. - Proprietary `x-` extensions multiplied, fragmenting the ecosystem. - Three newer specs: Arazzo (captioned "Arato") for multi-call workflows, AsyncAPI for event-driven APIs, Overlays for translations, configuration, and defaults layered over a spec. > [!quote] [00:06:06] > but there are fill in the gaps new standards like Arato which is the Italian for uh tapestry because it kind of woven the workflow of different API calls. #### ⏱️ [00:06:49](https://www.youtube.com/watch?v=PM9Kkfs6Ea0&t=409) Conway's law and the tools landscape - Conway's law (he dates it 1970, then 1967; the paper is 1968): organizations produce designs that copy their structure. Fragmented standards produce fragmented tools. - openapi.tools used to be a mess; now has a sponsor and better information architecture. - Postman grew from a test client into a docs tool; Insomnia is "another monster" and its founder is building a smaller open-source alternative after selling. - Three Write the Docs sponsors cover API docs; unnamed in audio, pointed to on the floor. #### ⏱️ [00:09:03](https://www.youtube.com/watch?v=PM9Kkfs6Ea0&t=543) No silver bullet, map your needs - Tools are laser-focused or do-it-all and neither will be complete. Proprietary ecosystems and monthly prices higher than comparable SaaS are, to him, evidence the problem is hard. - He shows a 2023 tooling survey from his last employer and calls it obsolete already. Advice: choose tools that fit your engineering and writing workflows, not the reverse. > [!quote] [00:09:46] > we shouldn't let the tools model our behavior but we should model your tools #### ⏱️ [00:10:29](https://www.youtube.com/watch?v=PM9Kkfs6Ea0&t=629) The Docusaurus and Redocusaurus example - Static sites with CSS templates rendering the reference: flexible, high maintenance, and a place AI might help. - At a tax-compliance SaaS (captioned "quadro," likely Quaderno) the team chose Docusaurus (Meta), which lacks native OpenAPI support, plus Redocusaurus, a plugin that renders the Redoc React component inside the site. #### ⏱️ [00:11:14](https://www.youtube.com/watch?v=PM9Kkfs6Ea0&t=674) Engineering lens: closer to the code - Docs-as-code: shipped code is the source of truth. Closer generation means lower maintenance and shared ownership across engineering and writing. - Aspiration: an engineer changes a route and the docs redeploy without a separate step. > [!quote] [00:11:14] > the closer to the code the better because with that we will achieve cert ownership between the different teams of your company #### ⏱️ [00:12:40](https://www.youtube.com/watch?v=PM9Kkfs6Ea0&t=760) Five sources for a spec - Hand-written: hard to maintain, linters help, owned by writers, a knowledge silo. - Traffic capture: a proxy watches real calls; someone owns the pipeline. - Annotations: metadata in code, updated in commits, but nothing fails when forgotten. - Automated tests: tests generate the spec and go red on drift. His team used a Ruby gem (unnamed; rswag fits). - Framework introspection: .NET 9 and FastAPI, where code is the spec and no tests are needed. > [!quote] [00:14:50] > the test go red so everyone knows like okay we forgot to update the documentation because this test will generate the open API spec #### ⏱️ [00:15:33](https://www.youtube.com/watch?v=PM9Kkfs6Ea0&t=933) Where AI helps, where it doesn't - Big-bang spec generation is unreviewable. Maintenance agents on pull requests can flag a missing spec update. - Traffic capture and annotations: AI helps at low risk, but CI never goes red so misses hide. Tests: misses show. - Personal preference: AI writes the tests that generate the spec, not the spec. - Framework introspection is deterministic; AI isn't; AI adds nothing there. > [!quote] [00:16:20] > no one can review a big big file JL or JSON and detect if the AI will hallucinate on some parameter or whatever > [!quote] [00:17:05] > I prefer it just write the tests that autogenerates the API with AI. That has proven in my personal experience to be much better > [!quote] [00:17:50] > So in this case AI makes no sense. #### ⏱️ [00:18:34](https://www.youtube.com/watch?v=PM9Kkfs6Ea0&t=1114) Product lens and personas - A slide of per-language OpenAPI libraries, deferred to the shared PDF. - The API is a product; treat the docs as a product too. Map personas by talking to users: a corporate integrator and a solo developer differ in deadlines, emotions, needs. - Tip: help selected customers integrate for free to learn where the API hurts. #### ⏱️ [00:20:47](https://www.youtube.com/watch?v=PM9Kkfs6Ea0&t=1247) Predictability: sandbox, versioning, changelog - Sandbox: document limitations and test data, and how to simulate errors only reachable in production, like a failed payment. - Versioning policy, an advance-warning window for breaking changes (one month is his example), migration guides, and a changelog that also serves AI readers. - CTOs can say no to an API; docs are what they judge. > [!quote] [00:22:15] > there's no marketing claim that can sell an API it's the docs so to sell your API you need to do all these things #### ⏱️ [00:22:15](https://www.youtube.com/watch?v=PM9Kkfs6Ea0&t=1335) Diátaxis and Arazzo for guides - Diátaxis (captioned "taxis"), by Daniel Procida (captioned "Daniel proa"), technical lead at Canonical: axes of action versus cognition and acquisition versus application yield tutorials, how-to guides, reference, explanation. - Docs as an organism: complete at any size, evolving. A first AI-assisted draft is acceptable as a starting organism. - Arazzo serves how-to guides by describing multi-call workflows and reduces AI guessing about call order. > [!quote] [00:24:28] > arato describes workflows not just an endpoint so for instance we are dealing with several API calls that perform a use case #### ⏱️ [00:25:14](https://www.youtube.com/watch?v=PM9Kkfs6Ea0&t=1514) Who reads your docs now - Relayed figures: a Cloudflare blog (captioned "cloer") on more than 50% non-human internet traffic; a sponsor benchmark (captioned "mainly," likely Mintlify) on more than 66% of docs traffic in July being AI. Neither is linked in the transcript. - New readers: autonomous agents and humans prompting assistants. New interfaces: MCP servers and CLIs. Claim: companies ship CLIs because MCPs cost more tokens; GitHub's CLI is the example. > [!quote] [00:25:14] > So more than 66% in July of all dogs is nonhuman is artificial intelligence. > [!quote] [00:25:57] > using CLA is because you use less tokens because NCPs uh consume a lot of tokens #### ⏱️ [00:26:40](https://www.youtube.com/watch?v=PM9Kkfs6Ea0&t=1600) Markdown, llms.txt, and token overhead - Second sponsor benchmark: AI crawlers make wrong assumptions about HTML; publishing Markdown reduces overhead. - `llms.txt` (captioned "the LLMs") is a small file mapping your site for machines, the robots.txt analog. Markdown plus `llms.txt` together shrink AI read overhead. - Motivation stated as energy and climate: "data centers will kill us all," delivered as hyperbole. #### ⏱️ [00:27:25](https://www.youtube.com/watch?v=PM9Kkfs6Ea0&t=1645) Wrap-up - Treat docs as a product. Shared ownership matters more than ever, which is why generation should sit close to the code. > [!quote] [00:28:10] > but then your docs are the API's interface #### ⏱️ [00:28:10](https://www.youtube.com/watch?v=PM9Kkfs6Ea0&t=1690) Q&A: human-centric APIs - Asked whether APIs risk being built for AIs, he answers with the product lens: engineers default to HTTP verbs and status codes; start from the person instead. > [!quote] [00:29:40] > software is always about people I always say that the difficult thing about software is always the people either building it or consuming it #### ⏱️ [00:29:40](https://www.youtube.com/watch?v=PM9Kkfs6Ea0&t=1780) Q&A: how traffic capture works - A proxy in the middle records calls and detects endpoints. It's an automation pipeline someone must build and own, similar to functional tests on a critical path, with the OpenAPI document as the output. #### ⏱️ [00:31:06](https://www.youtube.com/watch?v=PM9Kkfs6Ea0&t=1866) Q&A: the future of API docs - Hope: collaboration tooling closes the writer/engineer gap. Observation: teams shrink because of AI, "one with AI" as a team. - Identity crisis for people who loved programming and for writers, translators first. A responsibility to speak up against big tech practices. No easy answer offered. > [!quote] [00:31:50] > the teams are they today are more smaller than any than ever because of AI like a team of four or five people before now is one #### ⏱️ [00:32:34](https://www.youtube.com/watch?v=PM9Kkfs6Ea0&t=1954) Q&A: getting developers to own the spec - The host's experience: telling developers they own docs is how docs go stale. Rubio's answer: tests that generate the spec, explicit team conventions as knowledge management, leading by example. - The mechanism: change a route, the test fails, CI is red, the pull request can't merge. > [!quote] [00:34:02] > your continuous interation is red. So you couldn't merge the API the sorry the pull requests anyway. ## 📚 References The transcript itself contains no links; the following come from the video description or are primary sources for named entities. - [Documenting APIs: new era, same craft - Javier Rubio](https://www.youtube.com/watch?v=PM9Kkfs6Ea0): the source video, 34:45, uploaded 2026-09-22 by Write the Docs. - [Write the Docs Berlin 2026](https://www.writethedocs.org/conf/berlin/2026/): the conference page linked in the description. - [OpenAPI Specification](https://spec.openapis.org/oas/latest.html): the standard discussed from 00:03:47; version 3.1 added the `webhooks` object and aligned with JSON Schema 2020-12, which addresses the subset/superset complaint at 00:05:18. - [Arazzo Specification](https://spec.openapis.org/arazzo/latest.html): the workflow spec captioned "Arato"; 1.0 was published by the OpenAPI Initiative in May 2024. - [Overlay Specification](https://spec.openapis.org/overlay/latest.html): the overlay spec named at 00:06:06; 1.0 published October 2024. - [AsyncAPI](https://www.asyncapi.com/): the event-driven API spec named at 00:06:06. - [openapi.tools](https://openapi.tools/): the tools directory he says has improved with a sponsor and information-architecture work (00:07:34). - [Diátaxis](https://diataxis.fr/): Daniel Procida's documentation framework, captioned "taxis" and "ataxis" at 00:22:15 to 00:24:28. - [Docusaurus](https://docusaurus.io/) and [Redocusaurus](https://redocusaurus.vercel.app/): the static-site framework and OpenAPI plugin used in his worked example at 00:10:29; Redocusaurus wraps [Redoc](https://github.com/Redocly/redoc). - [Swagger Petstore](https://petstore.swagger.io/): the canonical example captioned "beta store" at 00:03:47. - [Model Context Protocol](https://modelcontextprotocol.io/): the "MCPS" and "NCPs" of 00:25:57. - [GitHub CLI](https://cli.github.com/): the "GitHub GX CLA" example at 00:26:40. - [llms.txt](https://llmstxt.org/): the proposal captioned "the LLMs" at 00:26:40, described as robots.txt for machines. - [ASP.NET Core OpenAPI support in .NET 9](https://learn.microsoft.com/aspnet/core/fundamentals/openapi/aspnetcore-openapi) and [FastAPI](https://fastapi.tiangolo.com/): the framework-introspection examples at 00:15:33. - Conway, M. E. "How Do Committees Invent?" *Datamation*, April 1968: the law cited at 00:06:49 and dated there to 1970 and 1967. - Cloudflare's non-human traffic figure and the sponsor's "66% in July" docs-traffic benchmark (00:25:14) are relayed without links in the transcript. Trace both before citing; the likely benchmark source is the sponsor captioned "mainly." ## 🗣️ Paraphrase Rubio's argument runs in three moves. REST won because it's flexible, and flexibility means no contract, and no contract means the documentation has to be the contract. Swagger, then OpenAPI, papered over that gap with a machine-readable description and a nice UI, but it never standardized the things developers trip on first: how to authenticate, what errors look like, how pages and rate limits and versions work. Those are yours to write. Around OpenAPI a fragmented ecosystem grew, with late webhook support, a JSON Schema mismatch, vendor extensions, and a tools market where nothing is complete and the expensive subscriptions tell you how hard the problem is. Arazzo, AsyncAPI, and Overlays fill some gaps. Second move: generate the spec as close to the code as you can, because that's what makes ownership shared instead of siloed. Of the five ways to produce a spec, only tests and framework introspection fail visibly when the API changes. Hand-written specs, captured traffic, and annotations all drift in silence. Use AI to write the tests that generate the spec, not to generate a spec nobody can review. Third move: the API is a product, so the docs are a product, and in practice the docs are what a CTO evaluates before saying no. Talk to your integrators, provide a sandbox with documented limits, publish a versioning policy and a changelog, and organize guides with Diátaxis. Now add a new reader: most docs traffic is machines. They want the same predictability developers want, they read Markdown better than HTML, and an `llms.txt` file tells them where to look. The craft hasn't changed. The audience has widened. ## 📰 Newsletter **For REST APIs, the docs are the contract.** Javier Rubio's Write the Docs Berlin talk (34:45, published 2026-09-22) is the tightest recent statement of a truth WordPress developers live with daily: the WP REST API has schemas per route, but the conventions that make it usable, authentication with application passwords and nonces, `_embed` and `_fields`, pagination headers like `X-WP-Total`, error envelopes with `code` and `data.status`, aren't in any spec. They live in the handbook. Rubio names exactly that gap at 00:04:31: OpenAPI standardizes none of authentication, errors, pagination, rate limits, or versioning. His most useful contribution is a ranking of five places a spec can come from, judged by one question: does CI go red when the API changes and the docs don't? Hand-written specs, traffic capture, and code annotations all fail that test. Tests that generate the spec, and frameworks that introspect their own routes (.NET 9, FastAPI), pass it. His AI advice follows from the same test: don't have a model generate a 3,000-line YAML nobody can review; have it write the tests that generate the YAML. The AI-era section will interest anyone shipping an MCP server. He relays a sponsor benchmark that more than 66% of docs traffic in July was non-human, argues companies ship CLIs over MCP servers because MCPs cost more tokens, and points to Markdown plus `llms.txt` as the cheap way to serve machine readers. None of those numbers are linked in the transcript, so trace them before repeating. The standards to go read: [Arazzo](https://spec.openapis.org/arazzo/latest.html) for multi-call workflows, [Overlays](https://spec.openapis.org/overlay/latest.html) for layering defaults and translations, and [Diátaxis](https://diataxis.fr/) for organizing the guides. [Watch the talk](https://www.youtube.com/watch?v=PM9Kkfs6Ea0). ## ✅ Action items #### DevRel - Developer advocacy: turn the "does CI go red" test into a 10-minute lightning talk with a live demo: change a route, watch the spec-generating test fail, watch the merge block. - Education: run one office-hours session walking through the five spec sources at 00:12:40 and asking attendees which one their team uses today. - Developer experience: audit any API quickstart you own against the five unstandardized conventions (auth, errors, pagination, rate limits, versioning) and add a section for each that's missing. - Developer marketing: adopt Rubio's line as a working rule: no marketing claim sells an API, the docs do. Route API launch copy through a docs review before publication. - Community management: add "relayed statistic, no source" as a standing tag for shared links; the 50% and 66% figures from 00:25:14 are the current examples. - Internal/external/cross-project: ask the Write the Docs sponsors named on stage for the "66% in July" benchmark and its method before anyone cites it. #### OSPO - Policy & Governance: write down who owns the OpenAPI document for each API in the portfolio and which of the five sources produces it. A spec with no owner is a hand-written spec by default. - License Compliance: Redoc, Redocusaurus, and Docusaurus carry MIT licenses; confirm before adoption and check any hosted portal vendor's terms for spec-content ownership. - Security Management: an `llms.txt` file and published Markdown are a deliberate exposure surface for crawlers; review what internal-only endpoints or notes could leak through them. - Software Inventory: an OpenAPI document generated from tests is a build artifact; record it in the SBOM pipeline with its generator and version. - Developer Support: publish a one-page decision guide for choosing between annotations, spec-generating tests, and framework introspection per language stack. - Community Engagement: the OpenAPI Initiative runs Arazzo and Overlays as open specs; consider participating if a hosting API needs workflow documentation. - Strategic Alignment: add "spec drift incidents per quarter" as a KPI, counting cases where docs and API disagreed in production. #### Community - Maintainers: for any project exposing a REST API, add a CI check that regenerates the spec and diffs it against the committed one, failing on difference. - Contributors: document the convention that an API change PR includes the spec change, and make the CI failure message point to the docs page. - Sponsors: if a docs-tooling sponsor funds work, ask for a public before/after count of stale endpoints. - Ecosystem: cross-project comparison of how REST APIs document pagination and error envelopes would show how far from a shared convention the ecosystem sits. #### WordPress - Core: the REST API exposes per-route JSON Schema via OPTIONS requests, which is framework introspection in Rubio's terms. Evaluate generating a full OpenAPI 3.1 document from it in CI so drift fails visibly. - Core Performance: no direct action from this source; nearest relevance is that machine readers hitting HTML docs waste bandwidth, and Markdown alternates reduce it. - Core AI: the Abilities API is a closed-set surface agents will consume; document it with the predictability rules at 00:20:47 (sandbox limits, versioning policy, changelog) from the first release. - **Core Program Team:** add "who owns the REST API reference and how is it generated" to the release checklist. - Mobile: no direct action from this source; nearest relevance is that the apps are REST API consumers and would benefit from a machine-readable spec. - Playground: a Blueprint that spins up WordPress and renders the REST API's OPTIONS output as a browsable reference would demonstrate introspection-as-spec in one page. - Community: no direct action from this source; nearest relevance is meetup content on API docs for plugin authors. - Training: draft a lesson on the five unstandardized conventions using the WP REST API as the worked example (application passwords, `X-WP-Total`, `rest_no_route` errors). - Marketing: no direct action from this source; nearest relevance is that API launch messaging should link the reference, not summarize it. - Support: catalog which REST API support questions map to the five conventions; the count tells you which handbook pages are missing. - Design: no direct action from this source; nearest relevance is the Diátaxis four-quadrant layout as an information-architecture model for DevHub. - Documentation: reorganize the REST API handbook against Diátaxis quadrants and mark which routes have a tutorial, a how-to, a reference, and an explanation. - Photos: no direct action from this source. - TV: caption quality is the accessibility failure of this recording itself; human-corrected captions on API talks are the fix. - Polyglots: Overlays are designed for translations layered over a spec; evaluate them for a localized REST API reference. - Accessibility: no direct action from this source; nearest relevance is that auto-captions mangled every technical term here. - Meta: WordPress.org's own APIs (plugin info, translations, events) lack a published OpenAPI document; generating one would be a concrete pilot. - CLI: WP-CLI is the CLI-over-MCP pattern Rubio describes at 00:25:57; document it as the token-efficient agent interface and measure whether that claim holds. - Hosting: hosts exposing platform APIs should ship a sandbox with documented limits and a versioning policy; both are named at 00:20:47 as what developers evaluate. - Tide: no direct action from this source. - Openverse: the Openverse API already publishes an OpenAPI document; check whether it's generated from code or maintained by hand, and which conventions it documents. - Themes: no direct action from this source. - Plugins: plugins registering REST routes should ship a schema per route; a review lint for missing `schema` callbacks is the smallest enforcement. #### The WPOCC - Programs: a documentation sprint focused on REST API convention pages (auth, errors, pagination) is a bounded, fundable unit of work. - Projects: no direct action from this source; nearest relevance is that The WP Open Community Collective could sponsor an OpenAPI generator for core. - Funding experiments: a microgrant conditioned on "CI fails when the spec drifts" is a measurable deliverable. ### FAIR - Technical independence: a spec generated from code in CI is reproducible by any operator; a spec maintained in a vendor portal isn't. Prefer the former for any FAIR-facing API. - Policies and covenants: publish the versioning policy and breaking-change window Rubio names at 00:21:31 as a covenant, not a page. - Productized governance artifacts: add "spec source" (hand-written, captured, annotated, test-generated, introspected) as a scorecard row for any API an operator exposes. ## 🧪 Hypotheses 1. REST APIs whose OpenAPI document is generated by tests or framework introspection show fewer documented-versus-actual mismatches per 100 endpoints than APIs with hand-written or annotation-derived specs, by at least a factor of 3. 2. Adding a CI check that regenerates the spec and fails on diff reduces the median time a spec stays stale after an API change from weeks to under one merge cycle. 3. For a fixed set of 20 integration tasks, an agent given a CLI plus its `--help` output consumes fewer total tokens than the same agent given an equivalent MCP server, as Rubio claims at 00:25:57; the margin is the unknown. 4. Serving Markdown plus an `llms.txt` index reduces the token count an LLM-based crawler needs to answer a fixed set of 50 questions about a docs site by more than 30% compared with the HTML version. 5. Docs sites for developer APIs see a majority of non-human requests in server logs; the "more than 66%" figure at 00:25:14 reproduces within 10 percentage points on independent sites once bot classification is applied. 6. Developers asked to review an AI-generated 2,000-line OpenAPI YAML miss more than half of a planted set of 10 hallucinated parameters, supporting the unreviewability claim at 00:16:20. ## 📊 Methodology - **Design for H1.** Sample 30 public REST APIs with published OpenAPI documents. Classify each by spec source using repository evidence (test files, annotations, generator config). Probe 100 endpoints per API with conforming requests and count schema mismatches. Compare mismatch rates across source classes; report with confidence intervals. - **Design for H2.** In one repository, instrument the gap between an API-changing commit and the spec-updating commit for the prior 12 months. Add the regenerate-and-diff CI gate. Measure the same gap for the following 6 months. The comparison is before/after in one codebase, so state that confound. - **Design for H3.** Build matched CLI and MCP interfaces for one API. Run the same 20 tasks through the same model with each interface, three runs each. Log input and output tokens per task from provider usage records. Report per-task and total. - **Design for H4.** Take one docs site, publish a Markdown mirror and an `llms.txt`. Run 50 fixed questions through a retrieval-augmented agent against the HTML version and the Markdown version. Count tokens retrieved and accuracy. Preregister the 30% threshold. - **Design for H5.** Pull 30 days of server logs from three developer-docs sites. Classify requests with a published bot-detection method and by user agent. Report the non-human share per site and compare to 66%. - **Design for H6.** Generate an OpenAPI document for a real API with an LLM, plant 10 parameter hallucinations, and give 20 developers 30 minutes to review. Score recall of the planted errors. ## ❓ Questions - Which sponsor produced the "more than 66% in July" docs-traffic benchmark, what year, and how did it classify a request as AI? - Does the token-cost advantage of a CLI over an MCP server survive when the MCP server exposes only a few well-described tools, or is it an artifact of oversized tool lists? - Which Ruby gem generated the spec from tests at his employer, and does its approach transfer to PHP test frameworks like PHPUnit or Pest? - The WP REST API already exposes per-route JSON Schema via OPTIONS. What blocks turning that into a committed OpenAPI 3.1 document that fails CI on drift? - How does Arazzo handle workflows spanning two APIs with different authentication schemes, which is the common case for a hosting platform plus a CMS? - Is "teams are smaller than ever because of AI" (00:31:50) an observation from his network or backed by any survey he could cite? - If docs are the API's interface, who signs off on a docs change the way an API owner signs off on a route change? - Do Overlays give Polyglots a workable path to localized API references, or do they only cover descriptions and not example values? ## 🔮 Future research - **Spec-drift measurement.** No shared metric exists for how far a published OpenAPI document diverges from the running API. A probe tool and a published drift index per API would let the five-source ranking at 00:12:40 be tested rather than argued. - **Arazzo in practice.** Arazzo 1.0 is 16 months old at the talk's date. Case studies of workflow documents spanning multiple APIs, especially with mixed authentication, are missing. - **Machine-reader instrumentation.** Docs sites need a standard way to distinguish agent traffic from crawler traffic from human traffic. Without it, "66% is AI" is unfalsifiable. - **Token cost of interfaces.** Controlled comparisons of CLI, MCP, and raw HTTP as agent interfaces to the same API would settle the claim at 00:25:57 and inform how hosts design agent access. - **Convention standardization.** Authentication, errors, pagination, rate limiting, and versioning remain unstandardized 15 years into Swagger. Whether RFC 9457 (Problem Details) and RFC 9530 (Digest Fields) style standards reduce hand-written convention docs is measurable. - **AI-generated spec review.** The unreviewability claim at 00:16:20 is a human-factors question with no study behind it. Planted-error review tasks would size it. ## 💡 Implications - **Practice.** Pick the spec source that fails CI. For PHP and WordPress stacks that means either a test suite that emits the spec or a build step that introspects registered routes and diffs against a committed document. Anything else is a hand-written spec with extra steps. - **Policy.** A versioning policy with a stated breaking-change window is a commitment to customers. Rubio's example is one month. Publishing it moves the API from "we'll tell you" to a term you can be held to. - **Security.** Publishing Markdown and `llms.txt` for machine readers is deliberate exposure. Review what those files index. Traffic-capture spec generation also records real request payloads, which may include secrets or personal data; the pipeline needs the same handling as logs. - **Education.** Diátaxis gives writers and engineers a shared vocabulary for "what kind of page is this." Teaching it alongside the five unstandardized conventions turns API docs from a reference dump into a navigable product. - **Funding.** The expensive-tooling signal at 00:09:03 cuts two ways: it argues for budget, and it argues for the do-it-yourself route with open-source components like Docusaurus and Redoc where a team has the engineering time. - **Labor.** The Q&A at 00:31:50 raises shrinking teams and an identity crisis for programmers and writers. The talk offers no fix; the implication for documentation programs is that shared ownership through automation matters more when there are fewer people to share it. ## 🧠 Learning styles assessment - **Reading level estimate.** Flesch-Kincaid Grade Level on the transcript body: approximately grade 8 to 9. Flesch Reading Ease near 65, reflecting short spoken sentences and non-native English cadence. Domain terms (WSDL, OpenAPI, JSON Schema, Arazzo, Diátaxis, MCP, `llms.txt`) push effective comprehension to an intermediate technical-writing or developer audience. #### 👀 Visual learners - Present: slides with the API timeline, the Petstore screenshot, the 2023 tooling comparison table, a per-language OpenAPI library list, and the Diátaxis quadrant diagram, all referenced in speech. - Improve: the five spec sources at 00:12:40 are described but never drawn as a ranked pipeline with a "fails CI?" column. That one diagram is the talk's most reusable artifact and is missing. #### 🔊 Aural learners - Present: full narration, a conversational Q&A, and audience laughter marking shared references. - Improve: the audio-only listener loses the Diátaxis quadrant and the tools table entirely. A 3-minute spoken summary of the five sources and the five conventions would serve podcast listeners. #### 🗣️ Verbal learners - Present: three explicitly numbered "insights," the woven-hanging etymology for Arazzo, the organism metaphor for docs, and the closing aphorism that docs are the API's interface. - Improve: WSDL, `x-` extensions, Overlays, and `llms.txt` go undefined beyond a phrase. One sentence each would cost 40 seconds. #### 🧩 Kinesthetic learners - Present: one worked example (Docusaurus plus Redocusaurus at a tax-compliance SaaS) and one mechanism to try (a spec-generating test that fails on drift). - Improve: no repository, no gem name, no CI snippet. The viewer can't reproduce the red-test demo from the talk alone. #### 🧠 Logical learners - Present: the five-source ranking is an ordered argument with a consistent criterion (does it fail visibly). The AI section applies the same criterion to each source in turn. - Improve: the Conway's law analogy at 00:06:49 is asserted, not shown. Naming two concrete standards-body splits and the two tool splits they produced would make it an argument. #### 🧑‍🤝‍🧑 Social learners - Present: references to the previous day's round table, a live Q&A, and pointers to sponsors on the conference floor. - Improve: no discussion prompt or community link in the transcript. "Which of the five sources does your team use?" would convert the room into data. #### 🧘‍♀️ Solitary learners - Present: a shared PDF is promised (00:18:34) for self-study of the per-language tooling. - Improve: no self-check. "List your API's auth, error, pagination, rate-limit, and versioning docs; which are missing?" is a five-minute exercise the talk sets up and never assigns. #### 🌿 Naturalistic learners - Present: the docs-as-organism metaphor from Diátaxis, and the explicit energy and climate framing for token reduction at 00:27:25. - Improve: the climate line is hyperbole ("data centers will kill us all"). Replacing it with a per-request energy estimate for HTML versus Markdown crawls would land the point with evidence. ## 📊 Accessibility assessment #### Screen reader semantics - Present: YouTube supplies page landmarks and player controls; the auto-transcript is machine-readable. - Improve: slides carry the tools table, the Diátaxis diagram, and the library list, none of which are read aloud in full. WCAG 2.2 AA 1.1.1 (Non-text Content) and 1.2.5 (Audio Description, Prerecorded) are unmet for slide content. #### Keyboard navigation - Present: the YouTube player is keyboard operable with visible focus by default. - Improve: nothing in the video adds barriers; 2.1.1 (Keyboard) and 2.4.7 (Focus Visible) pass via the platform. Chapters would add keyboard-reachable navigation and are absent. #### Contrast and readability - Present: unverifiable from the transcript; a conference recording of projected slides. - Improve: projected slides recorded on camera commonly fail 1.4.3 (Contrast Minimum) and 1.4.11 (Non-text Contrast). Post-production slide overlays would fix it. #### Text resizing and reflow - Present: the player scales and captions resize independently. - Improve: slide text baked into the video frame doesn't reflow. 1.4.4 (Resize Text) and 1.4.10 (Reflow) fail for the tools table and library list. #### Media and captions - Present: auto-generated captions exist and produced this analysis. - Improve: captions are wrong on nearly every technical noun: "Arato" for Arazzo, "whistle file" for WSDL, "beta store" for Petstore, "docuous" for Docusaurus, "Daniel proa" for Procida, "taxis" for Diátaxis, "cloer" for Cloudflare, "CLA" for CLI, "dogs" for docs, and "Tavi" for the speaker's own name in the closing. That is a 1.2.2 (Captions, Prerecorded) failure in substance. Human-corrected captions for 35 minutes of audio are the highest-value fix. #### Forms and interactions - Present: none in the video. The description links the conference page. - Improve: the promised PDF of slides isn't linked in the description. Adding it gives text-based access to every slide and satisfies the intent of 1.1.1 for slide content. #### Standards reference - Primary gaps against WCAG 2.2 AA: **1.2.2** (inaccurate captions on technical terms), **1.2.5** (no audio description for slides), **1.1.1** (slide content visual-only), **1.4.4 / 1.4.10** (baked-in slide text), **2.4.1** in spirit (no chapters for a 35-minute recording). Captions and a linked slide PDF fix most of it. ## 🌍 DEIB assessment #### Cultural breadth - Present: a Spanish speaker presenting in English at a Berlin conference, with an Italian etymology for Arazzo and a Canonical-based framework author cited. Examples span Meta, Microsoft, GitHub, Postman, Insomnia, and Cloudflare. - Improve: every tool and company named is US or Western European. Naming one API docs practice from an Asian or Latin American ecosystem would widen the frame. #### Inclusive language - Present: no exclusionary terms. Second person throughout. The one age reference ("if you are old like me in the industry," 00:01:32) is self-directed. - Improve: "data centers will kill us all" (00:27:25) and "another monster" (00:08:19) are hyperbole standing in for a claim; both are low severity and easy to replace with a number. #### Neurodiversity support - Present: three numbered insights give a predictable spine; the five-source list is enumerated. - Improve: no chapters, no slide PDF linked, and frequent mid-sentence restarts in the delivery. Chapter markers at the section boundaries used in the Notes above would let viewers navigate by topic. #### Representation - Present: one male speaker, one female host asking questions. Daniel Procida is the only other individual named. - Improve: no woman or non-Western practitioner is cited as a source. The API docs field has many; one citation would fix it. #### Psychological safety - Present: the speaker flags his own 2023 survey as obsolete, labels his AI-test preference as personal experience, and admits at 00:32:34 he has no easy answer to team shrinkage. The host jokes that nobody will hold a wrong prediction against him. - Improve: the identity-crisis passage at 00:31:50 touches livelihoods and is left hanging. A pointer to community or professional resources would give it somewhere to go. ## ✅ Logical validity #### Strong reasoning - **Deductive, 00:03:03.** If REST has no typed contract, and consumers need a contract to integrate, then whatever supplies the contract is the documentation. Valid given the premises; the premises are historically established. Clarify by noting that per-route JSON Schema (as in the WP REST API) is a partial contract. - **Criterion-based ranking, 00:12:40 to 00:15:33.** The five spec sources are judged by one repeatable test: does the pipeline fail when the API changes? Applying one criterion consistently is what makes the ranking an argument rather than a preference list. Strengthen by stating the criterion up front rather than letting it emerge at 00:14:50. - **Conditional, 00:14:50.** A test suite that doesn't go red on API change is equivalent to a separate hand-written spec. The equivalence holds: both are documents maintained by hand next to the code. Clarify by naming what makes tests go red (assertions against live responses, not fixtures). - **Deductive on determinism, 00:17:50.** Framework introspection is deterministic; a language model isn't; a nondeterministic step adds no value to a deterministic pipeline. Sound. It's the cleanest argument in the AI section. - **Concession against interest, 00:09:46 and 00:32:34.** He calls his own tooling survey obsolete and admits no answer to team shrinkage. Both raise the credibility of the surrounding claims. #### Fallacies - **Unsourced statistic, 00:25:14.** "more than 66% in July of all dogs is nonhuman is artificial intelligence" and "more than 50% of the traffic in the internet is nonhuman" arrive as attributions to a sponsor and to Cloudflare with no link, date, or method. *Fix:* name the report and the classification method, or present as "one vendor's measurement." - **Inference from price, 00:09:03.** Expensive subscriptions "to me is an signal that you know that it's difficult." Price also reflects market concentration, buyer budgets, and enterprise sales motion. *Fix:* state it as one possible reading and name the alternatives. - **Hasty generalization, 00:25:57.** "companies that have the power or care to do it are uh using CLA is because you use less tokens because NCPs uh consume a lot of tokens" rests on the GitHub CLI example and an unmeasured token claim. *Fix:* cite a measured comparison or state it as a hypothesis, which is how this analysis records it. - **Anecdotal generalization, 00:17:05.** "That has proven in my personal experience to be much better" is labeled as personal experience, which is honest, but it's then used to recommend a practice to the room. *Fix:* keep the label and add the sample: how many APIs, how many errors caught. - **Appeal to consequence, 00:27:25.** "data centers will kill us all basically because of the of the climate change" motivates token reduction with a catastrophe. The recommendation (Markdown plus `llms.txt`) stands on efficiency alone. *Fix:* drop the catastrophe, keep the token count. - **Slip, 00:06:49.** Conway's law is dated to 1970 and then 1967; the paper is 1968. Not a fallacy, an error in a supporting detail. - **Ambiguity from uncorrected captions, throughout.** "Arato," "quadro," and the unnamed Ruby gem make some entities unusable as cited facts. Not the speaker's fault; the fix is corrected captions and the promised slide PDF. #### Tone of voice - Conversational, self-deprecating, and structured around three announced "insights." Second person and contractions throughout ("if you are old like me," "you must make sure"). The register is a practitioner reporting what worked at one employer, with hedges like "this is an aspiration" (00:12:40) and "in my personal experience" (00:17:05) placed where the evidence is thinnest. Rhetorical heat appears twice, at "another monster" (00:08:19) and "data centers will kill us all" (00:27:25), and in both cases the underlying point survives without it. The Q&A turns reflective at 00:31:50, where the speaker declines to predict and instead names an identity crisis he doesn't claim to solve. That honesty is the tonal signature of the talk: opinions are flagged as opinions, and the mechanisms (tests go red, CI blocks merge) carry the weight. ## 🛡️ DARVO analysis Not applicable to this source. DARVO (Deny, Attack, Reverse Victim and Offender) describes a response pattern to accusation. This is a conference talk with a friendly Q&A; the nearest thing to a challenge is the host's remark at 00:32:34 that telling developers they own docs is how docs go stale, which the speaker answers with a mechanism (spec-generating tests that block merge) rather than deflection. For completeness across the three prongs: **Deny**: nothing is denied; the speaker volunteers that his survey is obsolete and that he has no answer to team shrinkage. **Attack**: no critic is attacked; tool vendors are compared on completeness and price, and sponsors are thanked. **Reverse victim/offender**: no such move appears. The one emotionally loaded passage, the identity crisis at 00:31:50, casts programmers and writers as affected by industry change, not as victims of any named party, and ends with a call to "speak up" rather than a grievance. ## 🎯 Conclusion The durable content of this talk is a test, not a tool recommendation: for any REST API, ask whether the pipeline that produces the reference goes red when the API changes and the docs don't. Hand-written specs, captured traffic, and code annotations all fail that test and drift silently. Tests that emit the spec and frameworks that introspect their own routes pass it. That criterion, stated at 00:14:50 and applied to AI at 00:15:33 through 00:17:50, is what makes "docs as code" a mechanism rather than a slogan, and it survives independent of Rubio's specific stack. The second durable idea is the list of what OpenAPI doesn't cover: authentication, error handling, pagination, rate limiting, and versioning (00:04:31), plus sandbox limits, a versioning policy with a warning window, migration guides, and a changelog (00:20:47). For the WordPress REST API, a hosting platform API, or an MCP server, that list is the outline of the guides you still write by hand, and Diátaxis (00:22:15) is the shape to put them in. Arazzo (00:24:28) is the standard to read for the multi-call how-to guides. The AI-era section is the weakest evidentially and the most quoted in practice. The 50% and 66% traffic figures, the MCP-versus-CLI token claim, and the Markdown-plus-`llms.txt` efficiency claim are all relayed from sponsors or stated from observation, with no link in the transcript. Treat them as hypotheses. The methodology section above gives one design for each. **Next steps for readers:** identify which of the five sources produces the spec for each API you document, and whether it fails CI on drift. If it doesn't, that's the first project. Then check your docs against the five conventions and the four predictability items; the gaps are your guide backlog. Finally, trace the "66% in July" benchmark to its source before repeating it, and fetch the slide PDF the speaker promised, because the auto-captions on this recording mangle every standard and product name he relies on. ## 🔄 Refactor Appendix — Documenting APIs: new era, same craft - Javier Rubio > Density: 2–5 Literature atoms (H3 pad), 0–3 Permanent candidates (H4 pad). > Emitted: 5 Literature, 2 Permanent. Resonance filter applied — the Cloudflare 50% > figure and the MCP token claim were kept out of the atoms as unsourced; the 66% > figure is kept as a specimen of a relayed statistic, labeled as such. > > Konik claim-header rules: present tense, declarative, ≤10 words, searchable, unique. > > Atomicity: one declarative sentence per atom. "and"/"also" → split. > > Tag pool: #bmf · #addendum · #xref · #articleseed · #storystem · #share · #aphorisms ### 📚 Literature Split Pad #### [H1] REST has no contract, so the docs are > [!quote] [00:03:03] > So the first insight of my talk will be the contract are the docs on some of these APIs. **Context & use**: - 00:03:03, closing the API history after SOAP (WSDL contract), REST (none), GraphQL (schema). - The premise everything else rests on. For the WP REST API, per-route JSON Schema is a partial contract; the conventions around it are still docs-only. **Tags**: #xref #aphorisms <!-- atomicity: 1 idea ✓ --> #### [H2] Spec-generating tests fail visibly when the API drifts > [!quote] [00:14:50] > the test go red so everyone knows like okay we forgot to update the documentation because this test will generate the open API spec **Context & use**: - 00:14:50, the fourth of five spec sources, and the one his team chose with a Ruby gem. - The operating criterion for the whole engineering section: a pipeline that can't go red is a hand-written spec by another name. Reused in Q&A at 00:34:02 as the answer to developer ownership. **Tags**: #xref #share <!-- atomicity: 1 idea ✓ --> #### [H3] Docs, not marketing, sell an API > [!quote] [00:22:15] > there's no marketing claim that can sell an API it's the docs so to sell your API you need to do all these things **Context & use**: - 00:22:15, after the predictability list (sandbox, versioning policy, migration guides, changelog) and before Diátaxis. - The commercial argument for docs budget. The mechanism: CTOs hold a veto and evaluate the docs, not the pitch. Pairs with the closing line at 00:28:10 that docs are the API's interface. **Tags**: #xref #aphorisms #articleseed <!-- atomicity: 1 idea ✓ --> #### [H4] Arazzo documents workflows, not single endpoints > [!quote] [00:24:28] > arato describes workflows not just an endpoint so for instance we are dealing with several API calls that perform a use case **Context & use**: - 00:24:28, placed in the Diátaxis how-to quadrant. "Arato" is the caption's rendering of Arazzo, OpenAPI Initiative, 1.0 in May 2024. - The standard to evaluate for any multi-call guide (create site, set secret, deploy) and for reducing agent guesswork about call order. **Tags**: #xref <!-- atomicity: 1 idea ✓ --> #### [H5] A sponsor benchmark puts AI docs traffic above 66% > [!quote] [00:25:14] > So more than 66% in July of all dogs is nonhuman is artificial intelligence. **Context & use**: - 00:25:14, attributed to a sponsor's open-source benchmark (captioned "mainly," likely Mintlify) with no link, year, or classification method in the transcript. - Keep as a specimen of a relayed statistic: precise number, named-but-unlinked source, no method. Trace before reuse; the Methodology section gives a replication design. **Tags**: #xref #share <!-- atomicity: 1 idea ✓ --> ### 🧠 Atomic Split Pad #### [P1] A spec that can't fail CI is a hand-written spec **Claim** (one sentence, Courtney's voice): Any API reference whose generation step can't turn CI red when the code changes will drift exactly like a document someone maintains by hand. **Evidence pointer**: [[#H2]] · [[#H1]] **Scope & conditions**: Holds for REST APIs without a typed contract, where the spec is derived rather than enforced. Weakens where the framework introspects its own routes (FastAPI, ASP.NET Core 9, WP REST API OPTIONS output), because the spec then can't diverge from the code even without tests. Breaks for conventions the spec doesn't express (auth flows, rate limits, error semantics), which stay hand-written regardless. **Links**: - [[Docs as code]] — because extends - [[Code annotations for API docs]] — because contrasts on failure visibility: annotations are in the repo but nothing fails when they're stale - [[WordPress REST API schema]] — because applies-in generating an OpenAPI 3.1 document from per-route OPTIONS schema in CI <!-- atomicity: 1 idea ✓ --> #### [P2] Docs are the API's interface **Claim** (one sentence, Courtney's voice): For an API sold as a product, the documentation is the surface the buyer's engineers evaluate, so its accuracy is a product-quality metric rather than a communication nicety. **Evidence pointer**: [[#H3]] · [[#H1]] **Scope & conditions**: Holds where a technical evaluator can veto adoption, which Rubio locates in the CTO at 00:22:15. Weakens for internal APIs with captive consumers, and for APIs consumed mainly by agents, where the machine-readable spec and `llms.txt` become the interface and prose guides matter less. The claim is about who decides, not about docs volume. **Links**: - [[Developer experience as product]] — because extends - [[Diátaxis]] — because applies-in organizing the guides that make up the interface - [[Every claim carries a fact]] — because contrasts on register: marketing claims versus verifiable docs <!-- atomicity: 1 idea ✓ --> ### ✏️ Fleeting Queue - [F1] Trace the "more than 66% in July" docs-traffic benchmark to its publisher and method; the caption says "mainly," likely Mintlify: https://www.youtube.com/watch?v=PM9Kkfs6Ea0&t=1514 #fleeting #inbox - [F2] Find the slide PDF Rubio promised at 00:18:34 for the per-language OpenAPI library list and the 2023 tooling comparison #fleeting #inbox - [F3] Identify the Ruby gem that generated the spec from tests at his employer (captioned "quadro," likely Quaderno); rswag fits the description #fleeting #inbox - [F4] Open question: does the WP REST API's per-route OPTIONS schema already satisfy the "fails CI on drift" test if a build step diffs it against a committed OpenAPI 3.1 document? #fleeting #inbox - [F5] Article seed: "Five places a spec can come from, and only two of them can fail": the ranking at 00:12:40 with a WordPress and Pantheon example for each #fleeting #inbox #articleseed - [F6] Test the MCP-versus-CLI token claim at 00:25:57 against a Pantheon MCP server and Terminus on the same 20 tasks #fleeting #inbox - [F7] Read Arazzo 1.0 and Overlay 1.0 specs; check whether Overlays cover example values as well as descriptions for a localized reference #fleeting #inbox ### → Things 3 (max 2 actions) - [ ] Inventory each API I document by spec source (hand-written, captured, annotated, test-generated, introspected) and whether its pipeline fails CI on drift: API docs review, 30 min #things - [ ] Trace the "66% in July" AI docs-traffic benchmark to its source and method before citing it anywhere: research, 15 min #things <!-- deep-read:sections end --> 📄 **Full text:** [[Full Document Contents/Articles/Documenting APIs New Era, Same Craft - Javier Rubio.md|Documenting APIs: New Era, Same Craft - Javier Rubio by Write the Docs]] ## Highlights - [00:03:03] it was a contract to with a schema catching was hard learning curve it was difficult there were others like uh um style type internal use uh for remote procedure calls. So I want to focus on rest and on the matter that it doesn't have a contract right and that it requires dogs. So the first insight of my talk will be the contract are the docs on some of these APIs. Right? So if we now switch to AP docs [00:03:47] history instead of API history, well who recognizes this is the beta store, right? [laughter] The example everyone used. So yeah uh it came swagger and with a nice UI because why not right? So swagger kind of filled that gap acted as a contract uh filling this barely type API. Uh so we had to standardize this way of describes the APIs with JSON or YAML. So, uh, JAML was more humanish for writing it, right? Uh, and it was designed to fill the gaps in ([View Highlight](https://read.readwise.io/read/01m37bc11sr3mhqjawdtpazgde)) - Note: [H1] REST has no contract, so the docs are - Tags: atom/literature/h1 - [00:14:50] make sure that the tests go red when the API changes because if you have a separate set of tests that in the end is like having annotations or like having a separate spec right so when like reach that point I was telling you about that when you change the code then it's uh in this case the test go red so everyone knows like okay we forgot to update the documentation because this test will generate the open API spec. So we the site of the AP API reference will will auto deploy and will uh everything will ship together and then there's also framework [00:15:33] inspection like for instance uh net since version 9 supports this and there are frameworks like fast uh fast API fastly for fast API sorry for python where your code is the spec right So that will be you wouldn't need even tests and I want to talk also where can AI help here right because many people yesterday in the runtime table asked me like okay but I can write the open API spec with artificial intelligence well if it's a big ban like it's not the same generating all your spec from one uh you know at the same time that ([View Highlight](https://read.readwise.io/read/01m37bc39pc531z3xkb880ac83)) - Note: [H2] Spec-generating tests fail visibly when the API drifts - Tags: atom/literature/h2 - [00:22:15] developers especially like the chief technical officers can say no to it right there's no marketing claim that can sell an API it's the docs so to sell your API you need to do all these things otherwise they won't buy in and even if the decision the final decision is not for the developers it depends on the type of business and company but they always can say no so you have to care about this so and the I have this recommendation the the taxis framework from Daniel proa which is right now who is sorry uh the technical lead at canonical I love this because it divides [00:23:01] uh the different type of guides. So this will serve to the personas that we ideally as I said made the map for but if you don't do it just follow this and it will help. So it divides four uh sections. So information reference. So if you look let me okay so one is what the user does like actions. So tutorials on how to guide is doing something uh on the yaxis down what the user knows. So if they want to connect the docs they need a Spanish they they need understanding is different than some ([View Highlight](https://read.readwise.io/read/01m37bc5e7g352a6mcapfpp067)) - Note: [H3] Docs, not marketing, sell an API - Tags: atom/literature/h3 - [00:23:44] person that already knows your business domain already knows how rest API works and they only need a reference they don't need to connect the dots but it's about what the user knows. Then on the left is about acquisition of skills. So it's like the user kind of steing it and to the right is more about the work. And I also like this metaphor uh he uses in the ataxis which is to treat the documentation as an organism like because people say okay but I don't have right now anything. I don't have guides where do I start? It doesn't matter if even if you start small only have the fast track to start or whatever [00:24:28] in it's complete in itself or if you did the first approach with AI it's okay it's an organism it will evolve but it's complete as as it is so uh I named arato before and it can help here too because arato describes workflows not just an endpoint so for instance we are dealing with several API calls that perform a use case and a a need to those users that you have, right? And this is great for how to guide, but also it avoids a lot of AI guessing. So you have this AI will, you know, treat your API better and avoid errors. ([View Highlight](https://read.readwise.io/read/01m37bc7rt56aqhy0dv5z8an3s)) - Note: [H4] Arazzo documents workflows, not single endpoints - Tags: atom/literature/h3 - [00:25:14] So uh new era artificial intelligence and I want to talk who is reading your dogs. There was this cloer blog about more than 50% of the traffic in the internet is nonhuman right now but then mainly sponsors here uh had this uh interesting open source benchmark of how they did it. So more than 66% in July of all dogs is nonhuman is artificial intelligence. So we have the new type of user not only developers AI as I said also values predictability and we have new use cases. So you will have either fully autonomous agents [00:25:57] trying to integrate your API or humans asking about how to do it, asking the AI concrete prompts to do it and new interfaces like MCPS, model context protocol which is a way to connect to external tooling for the AI and CLAs. And this is interesting because like the many big companies or companies that have the power or care to do it are uh using CLA is because you use less tokens because NCPs uh consume a lot of tokens. So in the end uh they offer a CLA for the develop for developers using their API like for instance the GitHub GX ([View Highlight](https://read.readwise.io/read/01m37bca7avpj0qsxwt56y76j5)) - Note: [H5] A sponsor benchmark puts AI docs traffic above 66% - Tags: atom/literature/h3