Why We Should View Docs as a Product

A talk from Commit Your Code 26. AI isn’t making documentation less important. It’s changing how people get to it: they might open a page themselves, or ask an agent to read it for them. Either way, the answer still depends on the docs being accurate and having someone responsible for them. That’s the case I make in this talk.

Docs deserve the same care as the product they explain.

What gets tricky is what happens when the docs are unclear or stale. An agent may keep going, and then the user’s task fails. So the talk comes back to a few practical questions. Who is this for? What are they trying to do? Who keeps the docs system running, and which team owns the feature details? Traffic tells you that a request happened. It doesn’t tell you whether the person finished what they came to do.

The numbers behind the talk

Three headline measurements anchor the traffic shift discussed in the talk. Thales measures bot and human traffic across the wider web, while GitBook and Mintlify measure agent and human requests on their own documentation platforms. A Cloudflare measurement provides AI-specific context. They cover different populations, windows, units, and classification rules, so they are separate observations — not one trend line.

The broader web result is a bot majority, not an AI majority. In its 2025 network analysis, Cloudflare measured identified AI bots at an average 4.2% of HTML requests, with dual-purpose Googlebot broken out separately at 4.5%. That distinction is why the talk moves from the broad automation result to the two documentation-specific measurements instead of treating every bot request as an agent reading docs.

Make docs work on the web first

Before I get into formats built for agents, I want to start with the web. Docs need to work there first. The mechanisms below already have defining specifications, which gives us a good place to start.

I’d still keep one maintained set of docs, with readable pages for people and machine-friendly formats for agents when they need them. Both paths should lead back to the same source.