Cerrando la Brecha: Documentando APIs para Humanos y Agentes LLM

Hola a todos y bienvenidos a mi charla. Hoy hablaré sobre cerrar la brecha, documentando APIs para humanos y también para LLMs. Así que antes de sumergirnos en la charla, hagamos una pequeña introducción. Mi nombre es Trust Jermin. Prefiero que me llamen Jermin, pero pueden llamarme Trust. Trabajo como defensor de desarrolladores en Upload Care, y también escribo artículos técnicos. Así que me encontrarán hablando mucho en línea sobre Upload Care y sobre la carga de archivos también. Pueden encontrarme en las redes sociales usando el handle @CodeJackaband. Es lo que uso para todos mis handles. Hoy vamos a hablar sobre cómo deberían escribir contenido tanto para humanos como para LLMs. A lo largo de la charla, cubriremos algunas cosas. Cubriremos por qué deberían preocuparse por escribir para LLMs, la forma en que escriben para humanos, cómo los humanos leen la documentación frente a cómo los LLM consumen contenido, cómo pueden escribir para humanos y también cómo pueden escribir para LLMs. Y algunas acciones muy inteligentes que pueden tomar hoy para asegurarse de que su documentación y sus tutoriales estén posicionados para LLMs. Y también veremos cómo pueden medir el éxito y cómo se compara para ambas audiencias, para humanos y para LLMs, y algunos recursos que podrían consultar mientras intentan escribir para ambos.

Así que entremos en eso. ¿Por qué es importante esta charla? Hay una nueva ola de IA ocupando el espacio antiguo en términos de cómo las personas buscan contenido y cómo las personas encuentran contenido y también cómo las empresas obtienen referencias o registros en estos días. Gilamo de Vassel hizo un tweet hace un tiempo que charge equity ahora refiere el 10% de sus registros para Vassel. Y también muestra que están sucediendo un par de cosas. Algunas razones por las que deberían preocuparse incluyen que charge equity actualmente tiene más de 800 millones de usuarios, usuarios semanales que son muy activos usando charge equity y también charge equity maneja más de 1 mil millones de consultas cada día. Es un número enorme de personas que dependen de charge equity y LLMs para hacer preguntas. Tomen nota, esto es solo charge equity que estamos usando como un LLM como un caso de uso. Hay otros también que podrían consultar. Y la encuesta de Stackoverflow de 2025 muestra que cinco de cada seis desarrolladores usan IA en su flujo de trabajo, posiblemente para escribir código, para hacer preguntas, para corregir errores o para manejar errores. Así que es un número muy grande si están tratando de llevar su producto a esos desarrolladores. Así que si esos cinco de cada seis desarrolladores no están descubriendo su producto a través de IA, entonces significa que algo está mal y debería ser corregido. Otras empresas también están obteniendo esto también. Esta es una captura de pantalla de una empresa que realmente está obteniendo referencias de charge equity. Y donde trabajo en Upload Care, también estamos viendo un aumento muy, ya saben, en el número de registros que estamos obteniendo. Y este gráfico muestra estos registros que han estado teniendo a lo largo del tiempo desde enero de este año.

Y hasta ahora, el número ha estado aumentando de manera muy consistente. Así que esto muestra que no deberían ignorar, ya saben, optimizar su contenido para IA y LLMs. En cambio, deberían estar optimizando su contenido para ellos también.

Así que antes, solía haber algo llamado DX, developer experience, que es más como en la capa superior de esto, es solo una buena experiencia de usuario, pero adaptada para desarrolladores. Pero ahora los humanos no son las únicas personas que intentan leer su contenido. Los humanos no son las únicas personas que intentan acceder a su contenido. Ahora, ahora tenemos agentes LLM, agentes de IA que están tratando de acceder a su contenido. Y así, el nuevo DX ya no es solo humanos solos. En cambio, es una combinación de una buena experiencia de usuario y una buena experiencia de agente. Eso es lo que crea el nuevo DX ahora mismo.

Entonces, ¿cómo pueden mejorar su DX y hacerlo tan accesible para todos? Así que primero, entendamos cómo los humanos leen el contenido, cómo un desarrollador típico revisaría su contenido al usar su herramienta. El primer paso que harán es posiblemente buscarlo en Google. Ahí es donde el SEO ayuda mucho. O podrían ir directamente a su URL. Y cuando están pasando por problemas o tratando de buscar algo, revisarán sus documentos y leerán de arriba a abajo para tratar de buscar algo. Si no pueden encontrarlo así, usarán la navegación o usarán cualquiera de las funcionalidades de búsqueda que ustedes tengan. Así que, en esencia, todo este paso muestra que el desarrollador social está buscando un par de cosas. Una, claridad en el flujo lógico de su documentación. Y también están buscando ejemplos y casos de uso. Así que todas estas son las cosas que necesitan para poder acceder al contenido en sus documentos y entender lo que está pasando. Pero en el caso de los LLMs, es un poco diferente.

Primero, un modelo LLM como que tokeniza tu documentación. Esto significa que descompondrán el texto en tus documentos en pequeños fragmentos o en tu tutorial en pequeños fragmentos. Y luego buscarán patrones a través de tu contenido. Así que, por ejemplo, si tus documentos o si tu tutorial técnico es sobre autenticación, definitivamente buscarán cosas relacionadas con seguridad y también contraseña e inicio de sesión también. Así que usando esos detalles, luego construye un contexto a partir del texto disponible que tiene. Y luego es capaz de, como, ya sabes, lanzar este contexto para poder entender de qué trata tu documento y poder proporcionarlo como respuesta cuando alguien lo solicite. Así que esto muestra que los LLMs necesitan datos estructurados, contexto completo y una relación clara entre las diferentes páginas que tienes en tus documentos o entre una sección de una página de documentación específica. Esto les ayudará a entender mejor lo que está pasando y poder recomendarlo mejor cuando sea necesario.

Así que algunas cosas que puedes hacer para asegurarte de que cuando se trata de humanos, estás haciendo tus documentos amigables. Así que es bastante diferente de cómo puedes hacer tus documentos amigables para LLMs. Hablaremos de eso en un momento, pero volvamos a los humanos. Así que típicamente, las cosas típicas a hacer cuando intentas hacer tus documentos lo mejor posible para un buen DX para un humano es proporcionar un lenguaje claro, conciso y libre de jerga. Tus documentos deben ser lo más claros posible. Deben tener una estructura lógica. Debe haber una visión general, concepto, referencia y tutoriales. Y típicamente hay diferentes tipos de guías que tienes en tus documentos. Hay una guía de inicio, referencias de API, guía de integraciones y, ya sabes, cosas así. También proporcionas ejemplos y casos de uso que los desarrolladores pueden usar. Y luego también proporcionas, ya sabes, muestras de código funcionales con mejor manejo de errores y cosas así. Y para la navegación también, proporcionas una buena navegación y un buen diseño para que ellos puedan navegar fácilmente y buscar lo que están y buscar lo que están buscando. Y luego también tienes funcionalidad de búsqueda para ayudarlos a buscar. Y también está la nueva de, ya sabes, tener búsqueda de IA incrustada en tus documentos de tal manera que la IA pueda responder preguntas al buscar algo en tus documentos. Así que si tienes todo esto, básicamente significa que estás haciendo tus documentos amigables para los humanos.

Pero cuando se trata de hacer que tus documentos sean amigables para LLMs, sucede de dos maneras o puedes aplicarlo de dos maneras. Así que una es en cuanto al contenido. La otra es la estructura de tu contenido. Así que la primera, en cuanto al contenido, hablemos de eso. Involucra, ya sabes, fragmentación, lo que significa dividir tu contenido en secciones autónomas para que cada una de las secciones tenga sentido por sí sola. Y luego, si estás tratando mucho con APIs, deberías utilizar la especificación open API para una mejor explicación de las capacidades de tu API. Y luego tener una nomenclatura muy consistente y parámetros para describir todos los endpoints para que cuando los LLMs busquen contenido en tus documentos, puedan entender qué está sucediendo y también cuando intenten rastrear tus documentos, debería explicar qué hace cada una de tus API.

Así que para tutoriales en términos de publicaciones de blog y otros tipos de tutoriales, tu tutorial debería seguir el patrón de elaboración de pregunta-respuesta. Te mostraré un ejemplo de cómo funciona esto más adelante en la charla. Pero entonces cada LLM, cuando un desarrollador o alguien le hace una pregunta a un LLM, proporciona una respuesta y luego explica la respuesta. Así que cuando intentas hacer que tus documentos sean amigables con la IA, también debería seguir ese patrón. Y veamos algunos ejemplos de cómo puedes implementar algunos de estos en términos de contenido. Así que el ejemplo que tengo aquí es solo un ejemplo simple de un documento que posiblemente estaba hablando sobre cómo usar un web book. Así que si fuera solo para humanos, podrías decir rápidamente configurar el web porque describir arriba quien lo esté leyendo lo entenderá perfectamente. Estoy bien.

Pero cuando se trata de usar IA, deberías proporcionar tanto contexto como sea posible al hablar. Así que esa misma frase puede entonces ser explicada más a fondo usando un ejemplo diferente que dice configurar los endpoints del web book. Proporcionas la URL, el método, los encabezados que necesita y también la respuesta esperada. De esta manera estás proporcionando tanto contexto como puedas para esa sección específica de tal manera que el modelo de IA pueda entender qué está pasando aquí y pueda indexarlo correctamente. Así que otro ejemplo de cómo puedes en cuanto al contenido es pregunta, respuesta, y elaboración. Así que este es un artículo que habla sobre la carga de archivos multi-parte. Así que la primera pregunta, la pregunta típicamente viene en forma de encabezado de lo que estás hablando. No tiene que ser una pregunta, pero lo más probable es que sea algo que sabes que tus usuarios preguntarán o algo que debería sentar las bases para explicar el concepto. Así que lo que debería seguir inmediatamente debería ser la respuesta a ese encabezado o debería ser la respuesta a lo que sea que estés hablando. Y luego más elaboración y contexto pueden seguir. Pero usar este método o usar este patrón ayudará a los LLMs a entender, OK, esto me está proporcionando la respuesta y puedo usar esta respuesta para proporcionar respuestas a quienes me vayan a preguntar.

Y luego también puede proporcionar más contexto basado en lo que le has explicado en tu artículo. Así que todo esto, cuando haces todo esto en cuanto al contenido, luego necesitas pasar a aplicar esto de manera estructural también. Entonces, ¿cómo puedes hacer que tus documentos sean amigables con la IA, ya sabes, implementando una mejor estructura? Así que lo primero que necesitas hacer es proporcionar un archivo LLMs.txt para un mejor contexto. De la misma manera que los rastreadores de Google dependen de un archivo robot.txt, los LLMs también dependen de un archivo LLMS.txt para un mejor contexto.

Así que este es un ejemplo de cómo se ve un archivo LLMS.txt. Así que esto es lo que usamos en UploadK. Así que te proporciona detalles sobre de qué trata el sitio web, de qué tratan los documentos, ya sabes, detalles básicos que pueden hacer que el LLM entienda de qué trata tu producto. Y luego pueden ser capaces de recomendarlo cuando alguien pregunte sobre algo. Por ejemplo, cuando preguntan sobre un cargador de archivos, obtienen algo relacionado con UploadK. Así que también está el archivo LLMS.txt, que proporciona un detalle completo sobre todo en tus documentos, todo en tu sitio web. Pero es un poco más grande que esto. Pero esto puede ser un punto de partida para ti. Y luego pasas a crear el archivo completo.

Así que otro ejemplo sería incluir la opción de exportación MagDana. Es muy posible que hayas visto esto en diferentes documentos recientemente. Así que la opción de poder exportar esa página de documentación específica sin ninguna estructura HTML, sino solo el contenido de MagDana en sí. De esa manera podrás hacer preguntas a los LLMs mejor y ellos podrán proporcionar una mejor respuesta porque ya les estás proporcionando los documentos y también con tanto contexto cuando quieren, cuando necesita ser solicitado. Así que tener una opción de exportación MagDana también ayudaría con eso. Así que una tercera forma en términos de estructura sería tener tus documentos en un servidor MCP.

Entonces, un servidor MCP es un protocolo de contexto de modelo donde puedes comunicarte, donde puedes proporcionar datos y proporcionar cosas para comunicarte con LLMS. Así que en este caso, estamos hablando de documentación. Entonces puedes proporcionar tu documentación a estos servidores. Hay varios servidores de código abierto a los que puedes proporcionar tu documentación que se pueden conectar fácilmente a cualquier LLMS. Así que también tenemos eso al final de la charla. Así que compartiré eso también. Así que tener tus documentos en un servidor MCP te ayudará a tener una mejor estructura y también a ayudar a los LLMS a descubrir tu contenido más efectivamente.

Y así, con todo esto, básicamente significa que ya no estás pensando en tratar de optimizar solo para humanos, sino que también estás pensando en la IA y los LLMS cuando consideras eso. Así que ahora mismo hay una nueva realidad sucediendo. Así que antes solíamos decir que el contenido es el rey y el SEO es la reina. Pero ahora mismo el SEO no es lo más grande que está sucediendo ahora porque hay una nueva cosa llamada GEO, que es la optimización de motores generativos. Así que casi todo el mundo que solía buscar respuestas en Google, ahora principalmente le pregunta a un LLM por una respuesta o rápidamente le pide a un LLM una retroalimentación sobre algo. Incluso cuando intentas buscar algo en Google, está Gemini. Gemini te da una visión general de lo que estás buscando. La mayoría de las veces realmente no tienes que desplazarte por los resultados de búsqueda, sino que puedes simplemente, ya sabes, ir con lo que Gemini te ha sugerido y cosas así. Así que GEO básicamente significa optimizar para el SEO en sí. Pero yendo más allá de solo optimizar para el SEO, sino también optimizar para LLM, que incluye cualquiera de los LLM, como Cloud, GitHub, Copilot, y, ya sabes, cualquier herramienta de IA futura que sientas que los desarrolladores usarán.

Así que cuando estás optimizando para GEO, básicamente significa que estás haciendo que tus productos sean a prueba de futuro de tal manera que puedan ser utilizados por otras herramientas de IA futuras también. Así que algunas cosas que puedes hacer hoy. Así que algunos pasos accionables en términos de lo que hemos discutido hasta ahora es uno, tener páginas clave auditivas que tienes en tus documentos o en tu blog para claridad independiente y para precisión de muestras de código para asegurarte de que, OK, son realmente precisas y proporcionan tanto contexto como puedan para cada sección específica que tienes y para probar esto. Si realmente si tus herramientas o tu producto están funcionando bien o son muy precisos o han sido descubiertos por los LLMs, puedes pedir a los LLMs que te den una muestra de código y cómo implementar tu herramienta y revisar estas muestras de código para precisión o revisar las respuestas que están proporcionando para precisión. Y también para descubrir, para asegurarte de que, OK, tus productos han sido descubiertos correctamente, crea un archivo LLMS.txt con tus URLs clave de documentación y añádelo a las raíces de tu sitio web. También compartiré contigo un recurso que también puedes usar para para mostrar más detalles o para implementar este archivo LLMS.txt. Así que si pruebas todos estos pasos, definitivamente verás algunas áreas donde estás fallando. Y consideraremos cómo puedes mejorar en eso ahora mismo. Así que cuando se trata de medir el éxito en términos de para humanos y también para LLMs cuando consumen contenido, son ligeramente diferentes. Así que la forma típica para un humano donde mides el éxito como escritor de documentación técnico sería medir las tasas de rebote, qué tan rápido las personas salen de tus documentos y también el factor de tiempo hasta mientras. Qué tan rápido es para un desarrollador implementar tu documentación y qué tan rápido es para ellos implementar tu guía de inicio rápido y cosas así. Y luego la retroalimentación de los desarrolladores y los tickets de soporte también. ¿Cuáles son las retroalimentaciones que los desarrolladores te están proporcionando? ¿Con qué frecuencia están recibiendo tickets de soporte en términos de cuántos problemas o errores están encontrando mientras usan tus documentos? Cuando se trata de LLMs, es bastante diferente. Así que las cosas que deberías medir incluirían la precisión del código generado por IA mientras usas tus documentos, la citación y frecuencia en las respuestas de IA cuando se les hacen preguntas y también qué tan exitoso es para los desarrolladores poder lograr algo mientras piden asistencia de IA sobre tu herramienta o sobre tu tecnología.

Para que puedas dirigirte a ambas audiencias, deberías configurar el seguimiento para ambas para poder saber dónde deberías ajustar o qué deberías hacer bien o en qué deberías mejorar. Así que cuando estás escribiendo para LLM, no significa necesariamente que estás reemplazando la escritura para humanos. En cambio, la mejora. Porque cuando tienes un muy buen LLM, un contenido muy bueno que está optimizado tanto para humanos como para LLMs, no solo ayuda a los humanos, sino que también ayuda a las máquinas que están ayudando a los humanos hoy a usar mejor tus herramientas. Así que asegúrate de que estás optimizando para esto.

Y también, mi consejo sería comenzar con claridad, comenzar haciendo las cosas tan claras como sea posible y todo lo demás seguirá si sigues los diferentes pasos también. Y así, hay muchas empresas que ya están escribiendo para LLMs. Así que algunas empresas, algunas de mis empresas favoritas que sé que ya están haciendo esto son MongoDB, Twilo, Vassal, Stripe y también nosotros en Upload Care, también estamos haciendo esto. Actualmente, estamos renovando nuestros documentos para asegurarnos de que, OK, está dirigido a ambas audiencias tanto como sea posible. Y sí, definitivamente siento que tú también deberías hacerlo.