> For the complete documentation index, see [llms.txt](https://stateofdocs.com/blog/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stateofdocs.com/blog/rethinking-documentation-for-ai-agents-a-conversation-with-mongodbs-dachary-carey.md). # Rethinking documentation for AI agents: A conversation with MongoDB’s Dachary Carey {% columns %} {% column width="16.666666666666664%" valign="middle" %}
{% endcolumn %} {% column width="83.33333333333334%" %} *MongoDB’s Dachary Carey has been* [*experimenting with how AI agents consume documentation*](https://dacharycarey.com/ai-research/)*. What started as a project to generate agent skills from docs turned into a broader investigation into how agents access, interpret, and use technical content.* {% endcolumn %} {% endcolumns %} *We spoke with Dachary about what she’s learned so far — and why many assumptions about AI-ready documentation don’t hold up in practice.* ### Your role at MongoDB sits somewhere between technical writing and software engineering. How did you end up there? **Dachary Carey:** My role at MongoDB is ‘programmer writer-ish’. It’s hard to communicate what we do because it straddles technical writing and software engineering, and we’ve experimented with a bunch of different titles. I joined MongoDB in 2021 as a member of a team documenting Realm, which was a mobile database company MongoDB acquired. I cut my teeth learning Swift there and writing mobile apps that used our product so I could learn how our product worked, and that sort of led me into exploring problem domains through software engineering. That’s a lot of what I’m doing right now: building tools, using engineering practices and science to understand the impact or implementation details of things. So I’m kind of in this weird related space now that isn’t exactly technical writing or engineering, but kind of all of the above. Our team grew out of the work we were already doing around testing code examples. For Realm, we wanted to make sure that the code examples we were showing developers actually worked, and the testing helped us understand and discover edge cases. That was a very engineering-focused approach to documentation that a lot of people who work in documentation don’t necessarily have in their background. So we thought we could help the broader organization start to adopt some of the practices we had been using on our little team. We sort of expanded into this macro code example quality and standardization-focused team, and we have continued to evolve our role within the organization. We started delivering sample applications. We help people set up repos for Jupyter Notebooks for people who are data scientists and want to do some things with our products. We have sample app repos for full-stack developers who want to learn how to use MongoDB as part of their full-stack apps. We kind of do everything code-related now, and we’re less than 8% of the writing organization at MongoDB. A lot of the other writing teams have more traditional technical writing backgrounds, and we’re trying to help them adopt the tooling that we’re creating and the standards that we’re proposing to sort of lift everything up on the technical side of things. ### You’ve also been researching and writing about how AI agents consume documentation almost by accident. Can you tell us about that? **DC:** It’s kind of accidental, first of all, which is fun. Around the beginning of the year, both I and our product teams independently proposed that MongoDB should publish some official [skills](https://www.gitbook.com/blog/skill-md). I thought our documentation should be the source for our agent skills because it already gets updated. We wouldn’t be maintaining a second source of truth somewhere else; it could just be repurposed. I actually spiked on generating and writing agent skills from our documentation using a manifest system and some tooling I built, and it produced really nice skills. But then I wanted to test them and see if they actually helped… and it turns out they did not. I learned a whole lot about how agents use content, and how the content that you give agents interacts with the content that they already know. There are a lot of — and I’ll use a developer term — ‘foot guns’ here in how the content can interact. While I was working on that project, I was working with Claude Code and having my agent look at a bunch of documentation sites to verify that some of the patterns I was trying to test for were actually accurate, up-to-date ways of working with things like APIs, or standard library calls. I observed that the agent had a lot of problems accessing content. Sometimes it would fail in ways that I could see, sometimes it would fail in ways that I couldn’t. It would make stuff up, which I then would go back and verify was not correct. That has now become a whole big thing. I’ve just started digging deeper and deeper into that, and what the impact is on documentation, and how we need to adapt as an industry to serve this new consumer. I think agents are here to stay, and we need to figure out how to make our docs work for them so they can understand our products, or else our products are going to fail, because agents are now doing so much of the coding. ### What’s the biggest misconception documentation teams have about AI-ready documentation? **DC:** A couple of years ago, [the `llms.txt` standard](https://www.gitbook.com/blog/what-is-llms-txt) came out. It was the idea that we could give this list of pages to an LLM crawler and have them go find it. I thought that was the standard pattern that all agents would use. Turns out agents didn’t even know about that — that was surprising to me. I think there are things that could be done to improve agent discoverability of `llms.txt`. In my observation, none of the agent platform providers that I’ve tested with yet — and I’ve only tested with three or four — have any sort of instruction in their web fetch implementation for agents to prefer Markdown or `llms.txt` as a source of discovery. I found that one time GPT-5.3 knew about `llms.txt` and went to that as a source of discovery, but every other time with every other agent, it did not happen. So it’s non-deterministic, and that’s very frustrating and inconsistent. The other thing that was a big surprise to me was a lot of silent failure. A page might be 20,000 characters, but there’s a mechanical limit for some agents on how much content they can view when they go view a web page — it might be 5,000 characters. Sometimes the agent knows that truncation happened and it can take action. But other times the agent has no idea that truncation happened, and it’s just silently not serving you 15,000 characters of your page, and therefore you’re missing important information that you needed to complete the task. At the moment, the detective work is very mechanical. I'll ask an agent to visit one page and then another without explaining why. Then I observe things like when it makes the web fetch call, what I can see about the web fetch, and what I can see as a follow-up action that it does. If it makes another call, or if it has some thinking output and says stuff about what it’s finding, I watch that too. I want to automate this somehow and design test suites that we can run and rerun with agents. One thing that did surprise me positively was summarization. Claude now delegates fetch tasks to a background agent, which is a different, smaller, faster model. I typically work with Sonnet 4.5 or Opus 4.6, and in the background they delegate subagents that are using Haiku to do summarization. When Haiku went to pages, it found good information and effectively summarized it. I know we have this perception of LLMs’ summary functionality being subpar, and I’m sure there are still cases where that’s true, but I think it’s improved a lot since I formed that opinion. I was really surprised and pleased to see how well it got the information that the foreground agent needed in a targeted way without blowing up the foreground agent with all kinds of unnecessary tokens in its context. What hasn’t changed is how inconsistent agent behavior still is. One thing I’m experimenting with right now is agent directives on the HTML versions of the page. I tell the agent there’s a Markdown version of this page and tell it to go and get it. I’ve found that very inconsistent so far in my testing. Agent plus model is a very specific combination, and what you get with one agent and model may be very different than what you get with the same agent and a different model. And because they’re non-deterministic, even the same model and same agent can behave differently. I think adapting for that and understanding that will help everybody who’s using these tools. ### Many people say that if documentation is good for humans, it’ll also be good for AI. Do you agree with that? **DC:** I have spicy takes, and I know some folks in the industry are going to be unhappy to hear this. I don’t think what’s good for humans is good for agents for a variety of reasons. Mainly, tokens are expensive and context is a public good. That’s not my phrase — that’s Anthropic’s phrase from their Claude ‘Skill Creator’ skill file, and it lives rent-free in my brain. Everything needs to access the context window: the user’s messages, the codebase, and whatever docs, pages, or content you’re putting in there. So agents need the smallest possible unit of docs that will help them complete their task. And that is probably not what we consider giving humans. \[Exactly how much context agents need] is something that’s hard to know — maybe unknowable. But I do think we can focus in on things that would be helpful. Our education AI team at MongoDB does testing with behavioral evaluations and questions about using our products. They ask models questions about using our products and measure whether the models produce the correct answers as outputs. And if not, can we make changes to our documentation to help the models know the correct answer? The answer is yes, we can. We’ve seen that bear out in practice. I think the next logical extension is moving beyond questions, to some task-focused evals. What are the tasks we think developers are trying to do with our products? How do models perform when we give them these tasks? If we give them more or less information in the context, does the performance get better or worse? When I was testing agent skills, I also found that the context you provide interacts with information that's already in the model's training data, as well as information that's available in the codebase it's working in. So it’s not a clean-room implementation question — it’s understanding how these different factors affect each other. I would love to do a very disciplined, testing-based approach to try to actually empirically figure out what is good and what is not. In a world where it is easier for LLMs to create documentation fast — and whether it’s good or not is a whole other question — as technical writers, it becomes our task to figure out what guardrails we need around these processes, and when we can use them and when we can’t. I think evaluation systems for whatever tasks your documentation needs to help humans and agents perform are going to become more and more important for documentation teams or engineers to own, because we have the context of both the structure and content. ### How do you think AI is changing the role of technical writers? **DC:** I think understanding user needs is the lens a lot of technical writers approach their craft through — it’s certainly what has appealed to me. And I think a lot of us consider ourselves user advocates because we’re using the products like users. We’re trying to help users get to where they need to be with the products. Agents are a new kind of user. So I think if we can overcome any objection or fear about the tools, and also help company leadership understand our role is shifting, not being eliminated, then we’re well positioned to move into the future with this new tooling. But there will be growing pains. I think there is something else that’s happening that is very subtle, and maybe we’re not grappling with it yet as a documentation industry, which is the users we’ve been serving. Speaking for my company and my products, they are developers. Developers are, with this new tooling, moving up and abstracting. What we were serving, the way we were meeting them, was in a very direct, “here’s the syntax, here’s the patterns, all this stuff is what you need.” The agents still need that — but the developers who are using agents need something different. They need that higher level of abstraction… and my opinion about it is still evolving as I’m watching this shift happening in real time. But I do think we have two distinct modalities emerging whose needs are different. We have been very focused on the products that we serve because we’re siloed by default. We’re doing this product’s documentation, and we assume a lot of times that when somebody has reached us, they have already decided to use our product, or they’re thinking about using our product. In this new higher level of abstraction, developers aren’t saying, “Make this thing with MongoDB,” unless they’re already using MongoDB. If they’re starting out with a new project or something, they’re saying, “Hey, I need a database to do this,” or even just saying, “Hey, here’s what I want to do.” And the agent is the one deciding if they need a database, and if so, which database to use. There are apps that do this already, and that’s represented in a model’s training data as: when I need to reach for a web app that has some persistent backend to store customer information, I already have this reference architecture for MongoDB or whatever company, and that’s the tool I’m going to reach for by default. Helping agents understand how your product fits in the picture helps, but also pre-supplying, “Here are the types of higher-level tasks, and here’s where we fit in and what features we have.” It’s figuring out how we help agents, who are working with users to perform tasks that are not specific to our stack, understand how we fit into what they’re doing. I haven’t seen anyone talking about that yet. I think there is a shift happening — product companies are lagging. If you’re not in the agent’s frame of reference as a reasonable way to solve this problem, they’re never going to come to your docs. Whether or not your docs can be are accessible to agents is a moot point. ### What advice would you give documentation teams trying to navigate all of this? **DC:** The first piece of advice is, if you have been worried about change, find some way to make your peace with that because change is here. It’s here. We’re in a period where we need to adapt. So acknowledging that and moving forward rather than resisting it is something I’ve seen some people need to be working on. From a practical perspective, if you don’t already provide `llms.txt` and Markdown versions of your pages, make that a priority. I think as this becomes more visible and also proves helpful for agents, having that functionality by default will get you ahead of the curve. The other thing is do some sort of audit, whether it’s using my tooling, personal testing, or whatever types of things you think your organization needs to try to understand the impact of this problem for your organization and prioritize accordingly. For things that are problematic, like long pages, how many are there? Do you have any idea from your traffic how many of your viewers are agents vs humans? If you can start to understand those things, you can prioritize where to spend resources. And if you’re already ready to adapt and move forward? Experiment. Try different things. Observe what happens. See if you can repeat those observations across different agents and LLMs, and extract principles from those observations that you can then apply back to the work you do and also share more broadly. I also think sharing across the industry is one of the best things we can do right now. A lot of people are doing experiments like this on their own and maybe not talking about what they’re seeing. That means we’re all moving slowly in different directions. If we share information, we can all move much more quickly because we can benefit from everyone else’s experimentation. *** *This interview was published on 8 July 2026, and conducted as part of research for the* [***2026 State of Docs report***](https://www.stateofdocs.com/2026/)***.*** --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://stateofdocs.com/blog/rethinking-documentation-for-ai-agents-a-conversation-with-mongodbs-dachary-carey.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.