Bridging the Gap: Documenting APIs for Humans and LLM Agents

Hi, everyone, and welcome to my talk. So today I'll be talking about bridging the gap, documenting APIs for humans and also for LLMs. So before we dive into the talk, let's do a little bit of introduction. So my name is Trust Jermin. I mostly prefer to be called Jermin, but you can call me Trust. So I work as a developer advocate at Upload Care, and I also write technical articles as well. And so you'll find me always talking a lot online about Upload Care and about uploading files as well. You can find me on social media using the handle at CodeJackaband. It's what I use for all my handles. So today we're going to be talking about how you should write content for both humans and LLMs. So over the course of the talk, we'll cover a few things. So we'll cover why you should care about writing for LLMs, the way you write for humans, how humans read Docs versus how LLM consume content, how you can write for humans and also how you can write for LLMs. And some very smart actions you can take today to make sure that your Docs and your tutorials are positioned for LLMs. And we'll also see how you can measure success and how it compares for both audiences, for humans and for LLMs, and some resources that you could check out while trying to write for both.

So why is this talk important? So there's a new wave of AI taking the old space in terms of how people search for content and how people find content and also how companies get referrers or get signups these days. Gilamo from Vassel made a tweet a while back that charge equity now refers 10% of their signups for Vassel. And it also shows that a couple of things is happening. So some reasons why you should care include this one charge equity currently has over 800 million users, weekly users that are very active using charge equity and also charge equity handles over 1 billion queries every single day. That's a huge number of people depending on charge equity and LLMs for asking questions. Take note, this is just charge equity that we're using as one LLM as a use case. There are others as well that you could also check out. And the 2025 Stackoverflow survey shows that five out of every six developers uses AI in their workflow, possibly for writing code, for asking questions, for fixing bugs, or for handling errors. So that's a very huge number if you are trying to get your product to those developers. So if those five out of every six developers are not discovering your product via AI, then it means something is wrong and it should be fixed. So other companies are also getting this as well. So this is a screenshot from a company that is actually getting referrals from charge equity. And where I work at Upload Care, we are also seeing a very, you know, increasing the number of signups that we're getting. And this chart show this signups have been having over time starting from January this year. And up to now, the number has been increasing very consistently.

And up to now, the number has been increasing very consistently. So this shows that you should not ignore, you know, optimizing your content for AI and LLMs. Instead, you should be optimizing your content for them as well.

So before now, there used to be something called DX, developer experience, which is more like on the top layer of it, it's just good user experience, but tailored for developers. But now humans are not the only people trying to read your content. Humans are not the only people trying to access your content. Now, we now have LLM agents, AI agents that are trying to access your content. And so the new DX is no longer just humans alone. Instead, it's a combination of a good user experience and a good agent experience. That is what creates the new DX right now.

So how can you improve on your DX and make it as accessible to everybody? So first, let's understand how humans read content, how a typical developer would go through your content when using your tool. The first step they will do is possibly they might search for it on Google. That is where SEO helps a lot. Or they might just go directly to your URL. And when they are going through issues or trying to look for something, they will skim through your docs and read from top to bottom to try to look for something. If they can't find it like that, they'll use navigation or they'll use any of the search functionalities that you have. So in essence, this whole step shows that social developer is looking for a couple of things. One, clarity to logical flow in your documentation. And they're also looking for examples and use cases. So all of these are the things that they need in order for them to be able to access content in your docs and to understand what's going on. But in the case of LLMs, it's a bit different.

First, an LLM model will sort of like tokenize your documentation. This means they'll break down text in your docs into tiny chunks or in your tutorial into tiny chunks. And then they'll look for pattern across your content. So, for example, if your docs or if your technical tutorial is about authentication, they will definitely look for things related to security and also password and sign in as well. So using those details, it then builds a context from the available text it has. And then it is then able to, like, you know, throw this context around to be able to understand what your doc is about and to be able to provide it as an answer when someone requests for it. So this shows that LLMs, they need structured data, complete context and clear relationship between the different pages that you have in your docs or between a section of a specific documentation page. This will help them to better understand what's going on and to be able to better recommend it when needed.

So a few things you can do to make sure that when it comes to humans, you are making your docs friendly. So it's quite different from how you can make your docs friendly for LLMs. We'll talk about that in a bit, but let's head back to humans. So typical, the typical things to do when trying to make your docs as good as possible for a good DX for a human is provide clear, concise and jargon free language. Your docs should be as clear as possible. It should have logical structure. There should be an overview, concept, reference and tutorials. And typically there's different kinds of guides that you have in your docs. There's a getting started guide, API references, integrations guide and, you know, things like that. Also, you provide examples and use cases that developers can use. And then you also provide, you know, code working samples with better error handling and things like that. And for navigation as well, you provide a good navigation and a good layout so they can easily navigate and look for what they are and search for what they are looking for. And then you also have search functionality to help them search. And there's also the new one of, you know, having AI search embedded in your docs such that AI can be able to answer questions when searching for something on your docs. So if you have all of this, it basically means that you're making your docs friendly for humans.

But when it comes to making your docs friendly for LLMs, it happens in two ways or you can apply it in two ways. So one is the content wise. The other is the structure of your content. So the first one content wise, let's talk about that. It involves, you know, chunking, which means breaking your content into self-contained sections so that each of the sections should make sense on its own. And then if you are dealing a lot with APIs, you should utilize open API specification for better explanation of your API capabilities. And then having very consistent naming and parameter to describe all endpoints so that when LLMs are looking for content on your docs, you should be able to understand what's happening and also when they are trying to crawl your docs, it should explain what each of your API does.

So for tutorials in terms of blog posts and other kinds of tutorials, your tutorial should follow the pattern of question answer elaboration. I'll show you an example of how this works later in the talk. But then every LLM, when a developer or when someone asks an LLM a question, it provides an answer and then explains the answer to them. So when you're trying to make your docs AI friendly, it should follow that pattern as well. And let's look at some examples of how you can implement some of this in terms of content wise. So the example I have here is just a simple example of a docs that possibly was talking about how to use a web book. So if it's were to be just human, you can quickly say configure the web because describe above whoever is reading it will understand that perfectly. I'm fine.

Another example of how you can of content wise is question, answer, and elaboration. So this is an article that talks about multi-part file upload. So the first question, the question typically comes in form of the heading of what you're talking about. It doesn't have to be a question, but it's most likely should be something that you know that your users will ask or something that should lay the groundwork for explaining the concept. So what should follow immediately should be the answer to that heading or should be the answer to whatever you're talking about. And then more elaboration and context can follow along. But using this method or using this pattern will help LLMs to understand, OK, this is providing me with the answer and I can use this answer to provide answers to those who is going to ask me. And then it can also provide more context based on what you've explained to it on your article. So all of this, when you do all of this for content wise, you then need to move on to applying this in the structural way as well. So how can you make your docs AI friendly by, you know, implementing better structure? So the first thing you need to do is to provide LLMs.txt file for better context. So the same way Google crawlers depend on a robot.txt file, LLMs also depend on an LLMS.txt file for better context.

And then it can also provide more context based on what you've explained to it on your article. So all of this, when you do all of this for content wise, you then need to move on to applying this in the structural way as well. So how can you make your docs AI friendly by, you know, implementing better structure? So the first thing you need to do is to provide LLMs.txt file for better context. So the same way Google crawlers depend on a robot.txt file, LLMs also depend on an LLMS.txt file for better context.

So this is an example of how an LLMS.txt file looks like. So this is what we use at UploadK. So it provides you details about what the website is about, what the docs is about, you know, basic details that can make LLM understand what your product is about. And then they can be able to recommend it when someone asks about something. For example, when they ask about file uploader, they get something related to UploadK. So there's also the LLMS.txt file, which provides a full detail about everything on your docs, everything on your website. But it's a bit larger than this. But this can be a starting point for you. And then you move on to creating the full file.

Another example would be to include MagDana export option. It's very possible you've seen this on different docs recently. So the option to be able to to be able to export that specific documentation page without any HTML structure, but just the MagDana content itself. That way you'll be able to ask LLMS questions better and they'll be able to provide a better answer because you're already providing them with the docs and also with as much context when they want to, when that it needs to be prompted. So having a MagDana export option as well would also help with that. So a third way in terms of structure would be to have your docs on an MCP server.

So an MCP server is a model context protocol where you can communicate, where you can provide data and provide things to communicate with LLMS. So in this case, we're talking about documentation. So you can provide your documentation to these servers. There are various open source servers that you can provide your documentation with that can be easily plugged into any LLMS. So we also have that at the end of the talk. So I'll share that as well. So have your docs on an MCP server and this will help you to sort of like have better structure and also to help LLMS to discover your content more effectively.

And so with all of this, it basically means that you are no longer thinking about trying to optimize for humans alone, but instead you are also thinking about AI and LLMS when you consider that. So right now there's a new reality happening. So before now we used to say content is king and SEO is queen. But right now SEO is not the biggest thing happening right now because there's a new thing called GEO, which is generative engine optimization. So almost everybody who used to Google for answers, they mostly now ask an LLM for an answer or quickly ask an LLM for a feedback on something. Even when you try to Google something from Google, there's Gemini. Gemini gives you an overview of what you're looking for. Most of the time you really do not have to scroll through the search results, but you can just, you know, go with what Gemini has suggested for you and things like that. So GEO basically means optimizing for SEO itself. But going beyond just optimizing for SEO, but also optimizing for LLM, which include any of the LLM, like Cloud, GitHub, Copilot, and, you know, any future AI tools that you feel like developers will use.

When you're optimizing for GEO, it basically means that you're making your products future proof such that they can be used by other future AI tools as well. So a few things you can do today. So some actionable steps in terms of what we've discussed so far is one, have auditory key pages that you have on your docs or on your blog for standalone clarity and for code sample accuracy to make sure that, OK, they are actually accurate and they provide as many context as they can for each specific section that you have and to test this out. If it's actually if your tools or your product are actually working fine or they are very accurate or they have been discovered by LLMs, you can ask LLMs to give you a code sample and how to implement your tool and review these code samples for accuracy or review the answers that they are providing for accuracy. And also to discover, to make sure that, OK, your products have been discovered properly, create an LLMS.txt file with your key documentation URLs and add it to the roots of your website. I'll also share with you a resource that you can also use for for showing more details or for implementing this LLMS.txt file. So if you try all of these steps, you definitely see some areas where you're lacking. And we'll consider how you can improve on that right now. So when it comes to measuring success in terms of for humans and also for LLMs when they consume content, they are slightly different. So the typical way for a human where you measure success as a documentation writer, as a technical writer would be you measure the bounce rates, how quickly do people bounce out from your docs and also the time to while factor. How quickly is it for a developer to implement your documentation and how quickly is it for them to implement your Getting Started guide and things like that? And then the dev feedback and support tickets as well. What are the feedbacks that developers are providing to you? How often are you guys getting support tickets in terms of how much issues or errors they are encountering while using your docs? When it comes to LLMs, it's quite different. So the things you should measure would include the accuracy of AI-generated code while using your docs, the citation and frequency in AI responses when they are asked questions and also how successful it is for developers to be able to achieve something while asking for AI assistance about your tool or about your technology.

In order for you to be able to target both audiences, you should set up tracking for both to know where adjustments or improvements are needed. Writing for LLM enhances writing for humans, benefiting both parties. Start with clarity and ensure optimization for humans and LLMs. Many companies, including MongoDB, Twilo, Vassal, Stripe, and Upload Care, are already writing for LLMs to target both audiences effectively. Consider adopting MCP servers like Context7, GitMCP, and VisionCraft MCP for better content accessibility.

Explore resources like LLMS txt.org for generating an LLMS file and Open API docs for APIs and HTTP requests. Companies like Vercel and Stripe have documentation adopting AI. Understand that not optimizing for LLMs may result in missing out on a significant developer audience. Utilize available resources to implement content optimization for humans and LLMs effectively. Thank you for listening to the talk and feel free to connect online for any further questions or discussions.