Good docs need structure, even as agents take over writing

Transcript

Transcribed by machine (Whisper) from the episode’s audio, so a word may be off here and there.

1. 13:27

   Yes. That's a great question. I think the most important thing, and this is what I tell everybody, is everyone goes up to me and our team and is like, Han, we need to work on better docs. What advice do you have for us to build better docs? I did that. We literally had a consultant call with Mintlefy. Oh, there you go. Because we're like, our docs are in docusaurus and no agent can parse them. Yes. And that's how we transition to you guys. I like a perfect example of this.

2. 13:54

   Yeah, a hundred percent. And you know, my honest answer to this, and this is kind of the secret of it all. This is my honest answer. Write better docs. Yeah, fair, fair, fair. And I think that, you know, it's partially because of the reality of, I think the first and foremost thing is that agents are read and read information like humans, right? It's just able to do that at faster scale, higher quantities and so forth.

3. 14:15

   But what is not a good substitute is having bad content, but then replacing that with all of these like protocols and like, you know, all the things that like a platform like Mintlify supports that to compensate. And what I will tell. Interesting. This is also different from what I assumed. My hunch was because I don't care about the person anymore. I just want to drown it out with information. So it has tons of contacts.

4. 14:39

   I'm going to give it every single example repo. So I'm going to throw it everything it needs all in a JSON. It doesn't even have to read it as a human. That's not true, though, is what you're saying. Definitely not. Oh, wow. Because the agent still definitely needs context clues. And it needs to know how to traverse and find the right information. The right section, the right segmentation. All of that stuff that I think mirrors how a person comes to understand and conceptualize information is still very much the case.

5. 15:09

   I think what we've actually found because we've actually done a decent amount of research on this is if you were to just give agent like a really large unstructured dump of information especially when it's poorly constructed poorly maintained poorly truncated it actually performs far worse than knowing how to segment it truncate it and so forth and I think the other note to that is my point here is that while a lot of those you know protocols or tooling matters like you know LMCXT having MCP servers now web mcp all that fun stuff just making sure the content is accurate it's up to date it even exists right if you don't have correct information out there or the content isn't out there right that's really bad really but does the human still have to do that my hunch is couldn't you just send um an agent to just go

6. 16:00

   scour it, try to build things, do it on its own, and then it decides how to best structure this information for the dogs. Exactly. And that is exactly the biggest change that we've seen over the past year. Nice, I segued that perfectly. Yeah, there you go. Which is that it's really about the authorship of content. What we've now seen is that obviously, just like the same way it evolved in software, agents are the primary writers and maintainers of content now. And one of the reasons for that is because it is necessity, right? Products are being shipped at record speeds and record pace, and really no one is able to keep up with how quickly things are evolving, right? Like, you know, you wait a week and some team shipped a new product or a new thing, and the importance of still communicating that product on how it works,

7. 16:46

   what it does, how to call the API, integrate the SDK, how to use it, what the use cases are are now more important than ever and or as just as important and i would argue more important because agents are consuming at higher volumes right but not but because like software is being produced so quickly and that information is still so important knowing how to keep up the pace of that ability to communicate is extremely extremely difficult if it's just humans and so now most documentation writing the some of the stuff that we do at mintlify and what we even see customers do themselves is just again use ai to melt maintain all that code as well wow but i guess there's still a lot of human taste that goes into it yes that i thought didn't matter at all but clearly i'm still relevant i'm just kidding my job is still relevant 100 i think um a lot of like

8. 17:37

   technical writers right now are like you know because we see in the industry are super afraid of like their jobs because they're like oh my goodness like i'm in developer relations i'm in technical writing or like i'm here working on like kind of communicating the product the team build and now it's going to be fully replaced by agents. The really important distinction is I don't think that's also the case either. What I'm seeing is that the same evolution that's happening in software development is happening in that world too, which is someone still needs to know how to steer it. Someone still needs to explain what the intention of that product is. Because code is so literal. Whereas, hey, here's how you actually use it to guide agents to actually provide that information talk about use cases talk with customers all that stuff still fundamentally human

9. 18:26

   it goes from this kind of like steering like this pure writing role into a steering role now i really appreciate you saying that i mean as someone who like i i worked as in this as technical writer software engineer developer relations like that was the best few years of