More MLOps.community episodes

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

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

Published 13 Nov 2026

Duration: 00:32:36

Documentation must evolve to serve both agents and humans, requiring strict accountability and rigorous quality to prevent operational risks and maintain trust in AI-driven workflows.

Episode Description

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 wi...

Overview

The conversation examines how AI agents are reshaping documentation for software products. The speaker argues that documentation for agents and humans require fundamentally different approaches: agents want exhaustive markdown with all context, while humans need visual, curated, and opinionated content. He observes that current documentation is "worse than it ever has been" because people are using agents to generate walls of text that help neither audience. He emphasizes that internal documentation - particularly decision records - has become more critical than external docs because agents need to understand why decisions were made to avoid redoing work differently.

The discussion covers practical challenges: agents lean on training data rather than fetching latest documentation, creating a speed-versus-accuracy tradeoff. The speaker describes how at one company, 500,000 docs were reduced to 5,000, making agent maintenance feasible. He also raises the accountability problem: as agents generate documentation, teams face incidents caused by outdated or wrong docs, and the "blame the AI" excuse is fading as performance reviews tie reliability to documentation ownership.

What If

  • What if you treated your decision log as a first-class artifact that agents can query?

    • Move: Start writing a one-paragraph decision record with a timestamp every time you make a non-obvious technical or product choice, storing it in a chronological file alongside your code.
    • Why Now? The speaker notes that "the value of that has never been greater because then an agent can see it and it won't try and do it a different way," and that without this trail, "you forget your own decisions let alone what your team makes."
    • Expected Upside: As a possibility, agents working on your codebase will stop proposing refactors that contradict prior rationale, reducing the "weeks of cleanup" incidents the speaker describes.
  • What if you audited your documentation for the 95% junk problem before scaling agent access?

    • Move: Inventory every doc, note, and scratch file in your workspace; delete or archive anything that is a stub, deprecated, or a copy, keeping only the 1-2% that is actively useful.
    • Why Now? The speaker reports that "one to two percent of the stuff you have is actually useful," and that outdated docs "are in the context for the agents and they're in your search," bloating retrieval.
    • Expected Upside: As a possibility, reducing your doc set to a manageable core (the speaker cites 5,000 as a workable target from 500,000) makes it "very doable for an agent to keep that in sync with the code base."
  • What if you split your documentation into agent-facing markdown and human-facing visual formats?

    • Move: For each piece of documentation, produce a full-context markdown version for agents and a separate diagram, checklist, or visual summary for human readers, rather than a single mixed document.
    • Why Now? The speaker argues the common assumption that both audiences need the same content is wrong: agents want "endless amounts of markdown all the context" while humans want "a diagram that shows the major pieces."
    • Expected Upside: As a possibility, human readers get "something that the agent couldn't get me" and agents get complete context without wading through visual formatting, improving both retrieval accuracy and reader satisfaction.

Takeaway

  • Write a timestamped one-paragraph decision record for every non-obvious choice and store it chronologically so agents and future-you can trace the rationale.
  • Audit all internal docs and delete the 95% that are stubs, copies, or deprecated; keep only actively useful content to reduce agent context bloat.
  • Produce separate agent-facing (full markdown) and human-facing (diagram, checklist, visual) versions of each document rather than a single mixed format.
  • Assign a named owner to every doc set and tie documentation quality to performance reviews, mirroring code ownership practices.
  • Treat documentation as part of the product: if a feature ships without docs, treat it as not shipped, per the principle that "communication is a defect" when interfaces are undocumented.

Recent Episodes of MLOps.community

9 Nov 2026 My AI Agent Bought Me A Car

Hermes agent uses reinforcement learning and trace-to-environment synthesis to enable continual self-improvement, balancing token efficiency with inference-time steering for better agentic performance.

2 Nov 2026 How Stanford Teaches AI Coding Now

AI agent development, verification loops, and go-to-market automation are reshaping software engineering and sales strategies.

29 Oct 2026 From Slop Code to Software Factories

"Tandem biking in Amsterdam's chaotic cycling culture led to a critique of AI-assisted coding's flaws, particularly its tendency to produce unmaintainable, poorly structured code, raising concerns about long-term software reliability."

22 Oct 2026 Token Maxxing Is Over and Here Is What Comes Next

"AI in software development offers benefits but faces challenges like nonsensical outputs and over-reliance; smaller, controlled models like Sonnet improve adoption, while measuring ROI and human-AI collaboration are key to success."

15 Oct 2026 Agents Acting Safely on Our Behalf

"Web infrastructure must evolve to support AI agents securely, with protocols like WebMCP enabling safe, deterministic actions while accommodating diverse interaction methods and user control."

More MLOps.community episodes