Why Stripe Cut 500,000 Internal Docs Down to 5,000?

What happens when AI agents start relying on the same messy docs your team already struggles to search?

Demetrios hops into a Waymo in San Francisco with Dave Nunez, founder and CEO of Falconer and co-author of Documentation for Developers. They talk about why developers and agents need different things from docs, why agents sometimes skip up-to-date instructions, and how a stale internal document can contribute to a production incident.

Dave shares how Stripe cut roughly 500,000 internal docs down to 5,000 worth maintaining. The conversation also covers how to capture the reasoning behind engineering decisions, when a diagram beats a wall of text, and who owns the fallout when an agent acts on bad information.

Timestamps:

[00:00] Hopping into a Waymo in San Francisco

[00:24] Meet Dave, founder of Falconer

[01:15] Why internal docs matter for AI agents

[03:24] What humans and agents each need from docs

[05:46] Testing how well agents use developer tools

[07:01] Why agents skip the latest docs

[09:42] Decision records and the reasoning behind the code

[14:04] Cleaning up stale docs and broken search

[15:29] How Stripe went from 500,000 docs to 5,000

[17:02] When a diagram beats a 10-page doc

[18:53] How conflicting docs can lead to an incident

[20:42] Who owns reliability when an agent makes a mistake?

[24:01] Treating documentation as part of the product

[26:38] Giving readers an escape hatch

[27:27] The cost of AI-generated fluff

[29:36] Wrap-up and post-show chat