Docs for Humans, Docs for Bots: Writing Open Source Documentation in the Age of AI Agents

Open source documentation has always had one job: help a human being get unstuck. Every structural decision in the heading hierarchy, the example, and the warning before the dangerous command was made with a human reader in mind. That reader gets confused, skips ahead, loses context, and needs to be guided. That reader now has company.

AI coding assistants, agentic workflows, and LLM-powered support tools are consuming FOSS documentation at scale, often before any human sees the page. When a developer asks an AI agent to configure a deployment pipeline, the agent is reading your procedural guide, interpreting your API reference, and acting on your error messages. When a support bot answers a user question, it is synthesising your documentation into an answer you never wrote and cannot review. The documentation you wrote for a human is now being parsed, chunked, embedded, and acted upon by systems that do not read the way humans do.

This creates a real and immediate problem for FOSS documentation maintainers. Agents are not confused by ambiguity; they resolve it silently, often incorrectly. They do not notice that a page is outdated. They cannot tell that a warning matters more than its position in the document suggests. They strip narrative context and act on literal instruction. And when they get it wrong, the human downstream inherits the consequences of a failure that happened in a doc they never read.

But this is not an argument for abandoning human-centred writing. It is an argument for being more deliberate about structure, precision, and trust signals in a way that serves both audiences simultaneously.

Drawing on real examples from FOSS projects, this talk walks through the specific documentation practices that make content reliably usable by both humans and AI consumers: heading structures that create navigable context, examples that demonstrate rather than assume, metadata and source links that let agents and humans alike verify what they are reading, and error guidance precise enough to act on without interpretation. We will look at where optimising for one audience silently breaks the other and how to find the middle ground that keeps your documentation trustworthy regardless of who, or what, is reading it.

This is a practical talk with a philosophical backbone. FOSS documentation is part of the commons. How we write it now will shape how it gets used, misused, and trusted for years to come.

1. A clear map of how AI agents consume FOSS documentation differently from humans, what they parse reliably, where they silently fail, and why documentation structure is now a trust and safety question

2. Specific, actionable writing and structure practices that serve both human readers and AI consumers simultaneously, including heading hierarchy, example design, metadata, source attribution, and error message precision

3. How to identify the places in your existing documentation where ambiguity is harmless for a human reader but actively dangerous when an agent acts on it

4. A framework for thinking about documentation trust signals the markers that tell both humans and AI systems whether a page is current, authoritative, and safe to act on

5. Why FOSS documentation maintainers need to be in this conversation now, before documentation structure gets optimised for AI consumption by people who have never written docs for humans