

13 Nov 2026 · 33m · 13 chapters

How AI agents change what “good documentation” means, why Stripe reduced internal docs from 500,000 to 5,000, and how to make docs legible, trustworthy, and accountable for both agents and humans.
Dave (CEO/founder of Falconer). Background: long-time documentation expert; wrote Documentation for Developers; works on internal documentation and “agent-ready” knowledge systems.
Agents need different content than humans (agents want lots of markdown/context; humans need visuals and crisp answers). Documentation quality is worsening because teams generate more “slop” and conflate agent vs human needs. Agents may ignore instructions and rely on training biases, so outdated docs can cause wrong tool usage. Treat docs as a product: assign ownership, timestamp decisions, and delete junk.
Stripe cut docs from ~500,000 to ~5,000. A customer’s search surfaced “Jason’s intern onboarding doc” (dead link) above the real onboarding doc. Vercel Docker launch: agents recommended competitors due to outdated assumptions.
Written by AI. May contain mistakes.
Discussing the changes in documentation practices over the years and the shift towards internal documentation.
“conversation I asked you what your feeling is on documentation now because it feels like you have to put a lot of onerous on the person that's writing the documentation.”
Exploring the challenges of creating effective documentation that serves both humans and agents.
“Like, what is going to happen to my craft?”
Examining how agents interact with documentation and the implications for human users.
“like you're expecting them to put their own time into actually going and looking at it.”
Highlighting the importance of decision documents for internal processes and clarity.
“Let's see how well the agent can use it.”
Discussing the need for clear decision-making processes and documentation to avoid confusion.
“how do the agents even read what you're writing in the first place?”
Exploring strategies to improve documentation for both agents and human users.
“What are other internal documentation things that you've been really enjoying?”
Explore the common issue of outdated and useless documentation in organizations.
“95%, let's be generous, is copies of docs, outdated docs for deprecated features.”
Learn how Stripe reduced their documentation from 500,000 to 5,000 useful documents.
“And the cool thing with agents is once you have this baseline, like Stripe, we took$500 ,000.”
Understand the role of accountability in maintaining accurate and useful documentation.
“And, and it's so great because I'm like a magnet for friends at companies where they're like, like I just heard the other day, somebody was like, we had the worst incident I've ever experienced in my career.”
Discuss the evolving perception of documentation as an asset and strategies for improvement.
“He's the one that actually talked about it.”
Discussion on the inadequacies of current documentation practices and their impact.
“because you go to any renowned company's doc site, it is that slop fluff.”
Casual conversation about personal connections and upcoming events related to the podcast.
“Like you can get the initial output from an agent, but the human rigor, cause you can, you can empathize with the end reader.”
Conversations about distractions in life, creativity, and the importance of context.
“Yeah, I just did one with Jesse, who created Superpowers.”

Get the gist, explore an idea or ask about something said.
On Agentic Conversations (formally mlops.community), what are the key points of this episode?
Automatic transcript. May contain errors.
0:03Demetrios: What's up folks? I'm Demetrios. We made it to sunny San Francisco and whenever I'm here, I enjoy chatting with my friends who are working on AI agents because they are seeing what is at the forefront of this whole industry. So let's go hop in a Waymo and have a conversation.
0:21Dave Nunez: What's up dude?
0:24Demetrios: All right, I'm here with Dave. We're doing podcasts in a Waymo, Waymo cast. you're the CEO and founder of Falconer yes and last time we talked when you were on the podcast it was all about documentation and writing for developers and I remember in that specific conversation I asked you what your feeling is on documentation now because it feels like you have to put a lot of onerous on the person that's writing the documentation. But these days, dude, and by the way, you literally wrote the book on documentation, the literal book, Documentation for Developers, you wrote. And so it's like, where are we at now?
1:10Demetrios: Because documentation has changed so much since three years ago when we chatted.
1:14Dave Nunez: Yeah. And I think at the very end of that conversation, you asked me like what I'm excited about or something. I'm like, actually, as much as I talked about external documentation, I'm more excited about internal documentation. And that was just like a weird kink. Like, why would you want internal docs, like for your teammates, you know, dozens of teammates, hundreds of thousands when you can have millions of Stripe developers. And that ended up being like a very lucky, weird thing to be into because that's what powers agents. I have a lot of feelings like it was a roller coaster at first because it's like, wow, It used to take me two weeks to write a changelog for a release.
1:52Dave Nunez: And now I can do that in 30 seconds. Like, what is going to happen to my craft? And then I realized, well, I always hated writing the changelogs. So please, generate those. And then it became very clear that documentation, I think, is worse than it ever has been. And like we're we're guilty of this kind of on purpose because we've been asking ourselves the past couple of years. And I've been talking to friends at the big labs that care like documentation has to change. Yeah. We don't know how we don't know why. Or I mean, we don't know like how to do it. But like agents need very different content than humans.
2:31Dave Nunez: And I think what everybody's doing is like, oh, I used to write bad documentation before. Now I can have agents write bad documentation for me. And so you go to a random site and it's just like walls of text. It's just slop. It doesn't help you. So it doesn't help the agents and it doesn't help the human. So I'm like more fired up than ever to like.
2:52Demetrios: There's more opportunity now that because we're pushing out so much more documentation.
2:57Dave Nunez: Yeah. Yeah. And people justifiably don't have to read it as much. So if they do read it, like who cares if it's 99 % agent traffic? If I'm going there as a human, it is extremely important. I need something the agent couldn't get me. I need to visualize something.
3:13Demetrios: Yeah, so it's more important than ever that if it is a human, like you're expecting them to put their own time into actually going and looking at it. It better be good.
3:24Dave Nunez: Yeah, it's the delivery method. Like if I'm an agent, I just want markdown. I'm going to read every single character on the page. Just give me markdown. Give me endless amounts of markdown.
3:34Demetrios: All the context. It doesn't matter. just give it to me.
3:37Dave Nunez: If I'm a human, I don't want to read Markdown. I don't want to read at all. So like, don't even give me text, like read my mind, show it to me in a format that I like. Some visuals. Yeah. And give the, give the Markdown to the clankers. I don't want to see that. But right now it's all meshed together and people just conflate it like, oh, agents and humans need the same thing. It's just like the opposite is true. Like just slough it off to my agents that are going to be doing the actual implementation. Like I want to, I want the big picture. I have different needs than my, than my agents.
4:07Demetrios: It's funny because I, up until now, have been saying that, oh, well, you know, you can write documentation that humans can read, but agents can't, but you can't do it the other way around where agents can read it and humans can't. But it's almost like, oh, now seeing your point, it is true that just because I can read it It doesn't mean I want to. And if it's not optimized for the human, it's going to be 10 times harder for me to actually sit there and read it.
4:39Dave Nunez: Yeah, we have multiple senses. And so the cool thing is like as we make video, as we make graphics, like agents can read that too. But agents don't have the feeling of, oh, shit, my boss wants me to do something or I need to like implement billing before we ship tomorrow. and that feeling of dread when you can't find a crisp answer do you support this form of off do you support this currency yes or no and you're like okay this must be a simple like thing i can verify and that feeling of dread when you land on the docks and they're terrible and it's like a wall of text like agents don't have that feeling they'll find the needle in the haystack if it exists yeah but if you're a human you know you have that feeling of dread and now you have that bad impression of this company um versus turning that into a positive experience of like hey come on in this is it's it's almost functioning like a marketing site like yeah hey come on especially for developers right exactly we put we put time into this you can do this with your eyes closed come back the next time tell your friends yeah so like really that like human part of it is more important than ever and that's what people i think are the worst at because it's the hardest thing to
5:44Demetrios: do ironically and there's another way that i've seen the ability for agents to grasp what your product does or how to use your product it's not so clear like how we write documentation for agents you can just put everything in there but then i've seen a company that does like evals on how well agents can use different tools i think they're 2027.dev they're doing super cool stuff because they're saying, look, the common tools out there, the Vercels, the tail scale, the whatever it may be, I'm giving my agent a lot of different tasks that need to use these tools. Let's see how well the agent can use it.
6:32Demetrios: And some tools the agent uses really, really easily. And we don't really know why other tools it doesn't. And I'm sure there's a lot of like, well, maybe it's because there's great documentation and maybe it's because that tool has just been around and there's more of that code out there in the world or maybe that's like a minus who knows but what what I'm trying to say is it's not clear why yeah why does it work so well on some tools and then
6:59Dave Nunez: not so well on others yes oh that's so good and this this reminds me why this is like a very very hard problem to solve like the old way it was it was a hard problem and we took the time to solve it at Stripe when it was just humans because it's information architecture, it's search, it's writing quality, it's layout, like it's a it's design, it's authoring experience. Like now it's very, very hard in a different way. But like what you're describing, how do the agents even read what you're writing in the first place? So like the legibility. And then there's these very interesting like mini research, like people have done like the the head of, she's high up at Stripe, Michelle Boo.
7:40Dave Nunez: She talked about like agents ignoring their instructions, like in the docs and like, how do you like prompt inject the agents to follow what's on the page and ignore their training data? Because agents for the sake of speed, they cannot travel faster than the speed of light. So they have to lean on their biases. What do I already know about Stripe? And I can just like ignore, like I'm already making these assumptions and givens. and so they're using outdated data they think they don't have to fetch the latest thing on this page and like an example for versell is all of a sudden they had this big docker launch and like the agents were still recommending competitors because they they were uh leaning on their training data i already know this thing so i'm going to give the the the um question asker the person that's asking me like does versell run on docker um uh an answer that is wrong because i think i already know it Yeah.
8:32Dave Nunez: And meanwhile, you want it to go crawl all the thousands of Vercel's latest pages to give you the right answer. So it's a really, really interesting problem to solve. Like, how do you make it legible and how do you get them to follow certain instructions properly?
8:47Demetrios: Yeah, the most up to date information, because sure, they can search. But if they think they already know it, then they're going to lean on. Oh, well, yeah, I already know. Yeah, I'm not going to search. Yeah.
8:58Dave Nunez: You have to make a trade off where do you want speed? If you want speed, the agent's going to make assumptions, lean on his training data, its inherent biases. And everybody is shipping 10x more, writing 10x more. So think about in two, three years from now, like it doesn't matter how fast the agents are. They're not going to be faster than the speed of light. Are they going to read through your 100 ,000 docs and quick starts? Like every time they get a question? No, they're going to lean on what they already know. So it's a very hard problem to solve that you just cannot lean on today's or yesterday's practices, which I think everybody is right now.
9:33Demetrios: Wow, yeah, because the problem is only going to get exponentially greater.
9:39Dave Nunez: So much, so much, yeah.
9:41Demetrios: We did talk about internal docs too the last time that we chatted. I have since kind of gone down a rabbit hole on the whole idea of creating a decision doc. Love it. And so if there are things that are done at your company, you have this decision doc on why it was done like that, who decided it, what the rationale was behind it. And so you can see that trail. It still feels like you're going to want to, like 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. Right?
10:18Dave Nunez: Absolutely. And not even an agent, but you want to see adults throw tantrums at work. It's repeating themselves or somebody not remembering the decision they made or somebody like we have this we have this feature for our agent remember this and i was just arguing about it for our lunch cuisine today i wasn't going to make lunch and i'm like falconer remember what my cuisine is tell the team um it's been used against me multiple times like when when i remember one time i was like you know said some off offhand combat uh comment about a a company i was like no we would never use that like that's the antithesis of our philosophy and later on they were becoming a prospect and a lead and I'm like guys this customer this company's so freaking cool like we should do a case study and somebody on my team was like you said you never wanted to be associated
11:04Demetrios: with this brand I was like I would never say that oh man and she's like at Falcon what did Dave say
11:09Dave Nunez: and it was like I never want to be associated with this and I'm like you just like you forget the your own decisions let alone what your team makes let alone like all the little offhand things you want your agent to use as checkpoints. So that is a, like, I think we're just at the beginning of like logging decisions, but yes, like that is the ultimate.
11:29Demetrios: And when somebody wants to onboard and they say, why do we do it this way? What is the reason and rationale behind that? And you can see that decision and say, you see that we used to do it this way. Then someone proposed this. And ultimately we went that because the pros are this and the cons were this. But then when you see that whole transformation, if something has changed, you can know maybe it's time to re-update this decision too.
11:57Dave Nunez: Absolutely. And that happens all the time. Smart people come in and frontier models do this too. You want it to fix one bug and it tries to refactor your whole code base because you made all the, it's like, no, don't touch it. It's there for a reason. And an engineer comes in and is like, why are we using Mongo? We need to rewrite all this in MySQL. And somebody's like here here are the many arguments we've had over the years and then it you know it starts to
12:20Demetrios: make sense yeah um but yeah absolutely or it can be well yes my sequel has since changed these things so it's worth us re-evaluating this one tiny thing that this vendor doesn't do that makes
12:31Dave Nunez: it a showstopper for us yeah and um and it's really easy to forget those and it's really easy to argue about those and it's just not in code like it's in people's heads yeah so which is
12:43Demetrios: another thing that makes it so hard because you go you say things and in slack it usually plays out in slack you're having this conversation it's like well why are we doing it that way oh because this this and this and you have this whole thread and you're like but that actually doesn't matter anymore does it and so there's people that are having to chime in spend their time and that potentially is not the most valuable use of their time right trying to defend decisions that were made in the past. What are other internal documentation things that you've been really enjoying?
13:17Dave Nunez: I think, I mean, the decisions are incredible because we just, we log things and you just need a timestamp. It's funny how people will just run in front of Waymo's because they know the Waymo will start. It has to stop. Yeah. It's, you get like cut off because this is like the nicest driver around. So the cars just go around, people run in front, they know it's safer than a human. Yeah. Stop sign. Yeah.
13:40Demetrios: It's my right of way. Always. You're not going to get flipped off by the Waymo.
13:45Dave Nunez: I think before we get to the cool shit, like decision records are incredible. And I love, and I'm telling everybody just write stuff down with a timestamp. You don't need to perfect it or make it like beautiful. You can do that later. If you just, you can, if you write it down and keep it in chronological order, like you can do stuff with that later. I'm not even I think internally people just have to clean up their junk they don't realize that 95 probably and and this is this has proved out true from doing this exercise at uber and stripe and then a bunch of clients when I was advising probably like one to two percent of the stuff you have is actually useful.
14:28Dave Nunez: 95%, let's be generous, is copies of docs, outdated docs for deprecated features. It's stubs, like just scratch pads. And all of these are Google docs, they're Notion docs, like whether people still read them, they're in the context for the agents and they're in your search. So when you go to search and they're bloating it, and then a lot of these search tools provide weight for age. So the older it is, the more I remember we were working with this, this customer that had like 8 ,000 employees. And the first thing I do when I search, they were using Notion to like test, like how good their search is.
15:05Dave Nunez: I'm like, I'm new to this company. I'm a new engineer. How do I get started? And the top hit was titled Jason's intern onboarding doc. Do not use this, but please read. And then you click in that. And it's like, this is the top hit because I was the first person to write an onboarding guide. But this is the true doc. Like, click this one. This is the real onboarding doc. And of course, you click that and it's a dead link. But like, it's just like people just are like, well, what are you going to do? You know, search is search. And I just refuse to take that as an answer. Get rid of all of the junk.
15:39Dave Nunez: Reconcile it. And now you start. And the cool thing with agents is once you have this baseline, like Stripe, we took$500 ,000. got them down to like 5 ,000 we actually cared about. Wow. Now, like at the time we had people, you know, keeping things up to date and it was terrible, impossible. Now you can, you get it down to those 5 ,000 docs. It's like very doable for an agent to like keep that in sync with the code base with tasks. It's not gonna be perfect, but you're gonna be like 90 % of the way there.
16:08Demetrios: Dude, and I can't tell you how many docs I don't delete because I'm like, there's probably one sentence in there that's actually valuable. Yeah. And I know that it's not important, but that one sentence. Yeah. Potentially could have value in the future so that I am too scared to delete it.
16:27Dave Nunez: Yeah.
16:27Demetrios: Everybody has that. Yeah.
16:29Dave Nunez: And you remember, oh, that took me so long to create. Like, I don't want to. It's like cleaning out your garage, but it feels so, so good to delete stuff because you right when you delete it, you never think about it again. You're not like and if it was important, who knows?
16:42Demetrios: You won't, know. Well, even when I do think about it because of that search problem, I can't find it. So I'm sitting there, I'm like, oh, didn't I create something like this before? And so I go searching for it and then I can't find it. And it's so frustrating because I know I've made it.
17:00Dave Nunez: Yeah.
17:00Demetrios: I just don't know where it is.
17:02Dave Nunez: Yeah. And other cool stuff too, like people internally love a good flow chart or a diagram. Don't give me a 10 page software development life cycle doc that was written by an engineer that's no longer here. And people give it to me and they're like, this is mostly out of date, but it's directionally good. Like give this a read, like, ah, FML. Give me a diagram that shows the major pieces and you can accomplish so much with just like the, the width of the page showing me, okay, we start here with a PRD and then that moves to a prototype and then that gets specced out and then like that alone is so much more useful so that's that's probably to answer your question like I would say look at the stuff that can just be distilled down to a diagram a workflow a checklist and like get rid of all the old context just delete it saying that it makes me think about bringing up the things in the moment and
18:00Demetrios: And how with the way we work, that's one type of doing it, type of way of doing it. But then you've also got like looking at the code base and how is the code base actually built. But when you get to a certain scale, I'm sure that the code base also is another thing that it is massive amounts of code and repos and everything that you now have this context blow problem on that side too. So not only do you have the Notion docs or the Google docs that give you English, but then you've got code that goes with it. And if the majority of the stuff doesn't match or it just is overwhelming to the agent, you're really rolling the dice on if you're going to get anything valuable back from the query that you've asked.
18:53Dave Nunez: Yeah, absolutely. And code is pretty pristine. That's what the agents were trained on. what they're optimized for and if you have dead code delete it but agents are going to know like how to traverse that and what to get out of it but yeah you're right they start to get confused when they're taking okay this is the code base but your name is tied to this documents conflicting with what's in the code and it's conflicting in this old jira or linear task so like i'm just going to flip a coin because i'm meant to please you and your name is on the code and your name is on the task, your name's on the doc.
19:26Dave Nunez: So I'm just going to make a call here. And, and it's so great because I'm like a magnet for friends at companies where they're like, like I just heard the other day, somebody was like, we had the worst incident I've ever experienced in my career. It was weeks of, of, of cleanup because an agent made the wrong call based on a document. Like it is, this happened to me at Uber, except it was humans not updating the documents. Like agents are going to do the same thing, but worse because they're going to write something down and they're going to make it see, and you're going to trust it because you're going to think like, well, it's here.
19:59Dave Nunez: I don't have to go ask the person who actually owns it because something is written down by Claude. So I'm going to trust it.
20:05Demetrios: It's more dangerous. Dude, that just makes me think about the people or the ones who have to actually clean up the mess once it happens, because this is almost like a latent problem until it's not. And then you get some kind of an incident and somebody can't figure out what the hell is happening because the documentation has been a mess for ages. Yeah. And, or the agent is trying to figure it out and it's making mistakes because of documentation. And so you almost don't realize how bad it is until something goes wrong.
20:41Dave Nunez: Yeah. Yeah. And we have been in a period of the last couple of years where you're allowed to blame Claude. You're allowed to blame the agents if something goes wrong. But as a few performance review cycles come around, people realize like, oh, I own reliability and my team's docs went down or some other team's docs caused it that were written by Claude. But I own reliability. I'm getting dinged in performance reviews. All of a sudden, they're going to start to care. things aren't going to be as like as laissez-faire and YOLO as before of just like trading you know blindly trading what Claude says blindly publishing it because now you're responsible so that's the when when people ask me about docs like what tool should we use what should we do a style guide I'm like start with accountability because if you if you put a name to a doc set and just like a code base or a repo people will figure it out how to care and the next step of that is during performance reviews like put it on the job ladder like are you responsible for the documentation uh people will figure it out it will all cascade like smart people will figure it out and i think that's just kind of been blown up the last couple years um but i already see it changing like ownership accountability people know how to measure performance when you're pairing with agents.
21:59Dave Nunez: And so I am optimistic that like, you'll start to see that like, oh shit, you cause an incident, somebody else's team wrote the docs, but it's your responsibility. It's your metric that you own. Like that's on you. Yeah.
22:13Demetrios: Well, and that, whereas before when, if or when Claude or Astro or whatever it may be, Codex causes the incident, it's kind of like, oh, because I was testing the limits of the coding agent and now that's not an excuse like you have to still be an engineer and you have to be the owner of whatever is happening like you're saying like you have to own reliability and so if that means that you can do it moving fast with 50 million coding agents cool go for it because you're able to architect your software factory in a way that you know it's going to be all right but if you can't like you can't use that as an excuse now my dog ate my homework I'm not able to do it yeah exactly especially if you're if you're
23:01Dave Nunez: b2b like no like the the their contracts at stake there's compliance audits there's like hard stuff at stake where it's not like you know the customer's gonna be like ah yeah got us too um no you have to figure out a way to paper over github if it's going down like if us it used to be okay if us east went down because everybody went down and then it's like well you kind of have to figure out a way to be highly available no matter what like your customers don't give a shit if it was amazon's fault yeah um so i'm starting to see responsibility accountability um uh come back which is which is a good sign i think for everybody what are some other tricks or
23:44Demetrios: ways that you've seen it done well that you've said put names to the accountability just have a document that says who owns what and that will figure itself out another one is put owners on documentation are there other things that you've seen to work well you have to treat documentation
24:03Dave Nunez: as part of the product like that one is evergreen if the if the product is ready and you ship it it's not documented then you don't care about docs you might as well not even do them because like who cares and internally you have to treat it the same way like there is this amazing it's like the holy scripture of documentation people that Jeff Bezos had written some memo. I don't know the pronounce name. Who's the Gastown guy? Steve Yege. He's the one that actually talked about it. And it's so funny. It's written in like a readme in a GitHub repo buried somewhere. But at one point, Bezos was like, communication is a defect.
24:42Dave Nunez: If people are talking to each other, that means that you don't have properly designed interfaces that are well documented because you should communicate through interfaces and well documented APIs, not through meetings. And I love that because it's like the introverts manifest of like, don't talk to me. I don't want to talk to you, like document your stuff and then we'll socialize over lunch. But I don't want to socialize or, you know, have to stop what I'm doing to explain how this, this endpoint works or how to get going. And, um, and so that is, I think that was like the the early microservices type of philosophy but I think that still is actually more important than ever your team should be an interface to the rest of the company so how do you what's your operating model what are the tools you use if you do have internal services or infra like how do I connect my tools to it because the cool thing is now it's like agents can do more human like things so they want to know what your working hours are what your communication preferences are, what your roles or responsibilities are, because they can do so much with that information.
25:46Dave Nunez: Like, don't schedule a meeting to talk about stuff that could be written down.
25:51Demetrios: Yeah. Ooh. Yeah.
25:53Dave Nunez: So you talk to so many people across the space, like, and I'm sure you have opinions and they have opinions on the future of documentation. Like, what's the opinion you've formed recently?
26:06Demetrios: So when it comes to, dude, underappreciated asset is what I think. I like that. Doc should be an asset, right? And that's why I love talking to you because you are so deep in this practice and this craft that you understand all the ways that we can make it an asset rather than a liability. and I think the first time that we chatted I quote this all the time to folks how you would think about little micro almost philosophical things or psychological things that the people that are reading the documentation would have to go through and that was with the escape hatches and so what you said was that you would always in any documentation that you wrote have a few paragraphs in, is this what you were looking for?
27:02Demetrios: Or was it something along the lines of this, which is similar, almost like a recommender system of docs that you could have meant when you were looking for this so that somebody could traverse easily and not have to read through the whole documentation. That is what I look at as a document being an asset because I am not wasting of my time when I am looking through the docs. And the fact that it's so easy to churn out so much slop, we all are getting sick of reading slop. And I now have come to a point where I say to people, if it takes me longer to read your document than it took you to write it, I'm not going to read it.
27:47Dave Nunez: I call that a brovella, like a novella. If it took longer to read than it took you to generate, like you're just, you're forcing your lack of rigor on me. Exactly. And it does, like, if you go to any random, this is why I'm so angry and fired up about like docs today, because you go to any renowned company's doc site, it is that slop fluff. And it feels like I'm getting the Yankee candle. You know, you walk into like a Bed Bath & Beyond, it's like, ooh, somebody's baking cookies. Shit, that's just. like the cookie Yankee tricked me and and yeah like you get repulsed after a while that's what I feel disrespected right somebody just disrespected my time so hard that they look
28:30Demetrios: through and they think that I'm gonna sit spend my time which is the only thing I can't get back absolutely the most precious thing on in our lives and now I have to sit there reading some slop that you generated. Yeah. That for me is why I feel like it is an underappreciated asset because as of now, it's okay to do that. Like the norms haven't changed, but I get the feeling that enough of us are going to read enough crap that it's going to start really dinging your reputation in ways that you don't want. And so the next order effect of that is going to be that you're not going to put it out there or you're at least going to edit it before you generate it.
29:13Dave Nunez: Yeah. Yeah. That's a good way to put it. Like the, the rigor is missing. Like you can get the initial output from an agent, but the human rigor, cause you can, you can empathize with the end reader. So like, what would you want to read? I want to feel smart. I want to feel accomplished. I want to feel like a moron, you know, reading your instructions because I don't
29:35Demetrios: understand it exactly well dude this has been great man I appreciate you coming on here and talking docs with me yeah anytime are you coming to can you come to agent cohen I be I was if this
29:47Dave Nunez: was Friday but now that it's Monday I have to go home oh yeah yeah because you're based on us I'm in Santa Barbara that's right yeah so I spent like half my week up here where it's like an hour away right it's close to san jose though right 400 miles south oh 400 miles it's 100 miles north of la oh santa barbara is closer to la yeah oh i'm thinking of santa clara that's why i was like
30:14Demetrios: ah santa clara's close right no santa barbara santa barbara yeah so i i fly up um every week well all the more why this is so cool that you did this and we made it happen yeah this is fun
30:26Dave Nunez: How many of these have you done? Are you doing?
30:29Demetrios: I have one more. Yeah, I just did one with Jesse, who created Superpowers. Do you know that pack? Speaking of writing and all that fun stuff.
30:39Dave Nunez: That sounds familiar. The Superpowers Skill Pack. Super cool. I saw you talk to Zach, which was cool. He's one of our angels.
30:48Demetrios: Oh, yeah. Oh, nice. Dude, his stuff was really good. It's a while back now, but yeah, it was very cool.
30:55Dave Nunez: And he's a good writer. Yeah.
30:57Demetrios: Oh, yeah. He takes it seriously.
30:59Dave Nunez: He writes a lot about software factories, which is cool. Yeah. Yeah. And really nice. And then we have our big GA launch on Wednesday. Ooh. Dude, that's huge.
31:10Demetrios: Tell me when it goes out so I can, you know, reshare, like, comment. I will. Yeah. Yeah.
31:16Dave Nunez: That would be huge. Thank you. Very cool. Yeah.
31:19Demetrios: And I'll send you this recording. recording, hopefully, give me like two weeks, potentially three, for it to go out, you know, but if you want it so that you can make like, you know, shorts and all that fun stuff, I'll send you that too.
31:38Dave Nunez: That'll be killer. Oh, I'm remembering now you posted about my Neuralink content. The sad part is I actually believe it. I was like, I had to think what could disrupt me.
31:53Demetrios: neural link shit oh wait but now no there's too much noise yeah talk about context yeah like context bloat and we really got to get better because oh man just like meditating when i'm trying not to think yeah all i'm doing is thinking do we have the right mustard for the vinaigrette i'm making later exactly dude how long do we have with climate change yeah i'm trying to think of
32:18Dave Nunez: like all the stuff that pops in my head when trying to meditate.
32:21Demetrios: Oh, man. Yeah, just such random shit. And then you have one thing that might be valuable. Like, oh, should I stop meditating? Because I need to, I don't want to forget this one. Thanks, dude.
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