Lo que me enseñó crear un asistente de documentación con IA sobre la redacción técnica
La mayoría de los redactores técnicos no creamos agentes de IA. Los documentamos. Asistimos a la revisión del sprint. Leemos los registros de decisiones de arquitectura. Después averiguamos cómo explicar un proceso de recuperación a alguien que solo necesita que su integración funcione para el viernes.
Aun así, yo creé uno.
Se llama Artie, un asistente de documentación basado en IA que desarrollé con Algolia. Funciona dentro de este sitio de documentación. Crearlo me enseñó más sobre redacción e IA que cualquier charla de conferencia.
Esto no es un recorrido por el diseño de Artie. El caso práctico lo cubre. Esta entrada trata de las lecciones más generales:
- Qué son realmente los agentes de IA
- Cómo funciona la generación aumentada por recuperación en la práctica
- Por qué la ingeniería de prompts se parece más a la redacción técnica de lo que la mayoría cree
- Qué significa todo esto para quienes trabajamos en este pequeño mundo nuestro
Qué es un agente de IA y qué no lo es
La gente aplica el término «agente de IA» a todo, desde un corrector ortográfico hasta el autocompletado. Las diferencias importan. No toda función de IA es un agente. Un corrector ortográfico con aprendizaje automático no lo es. Una sugerencia de autocompletado tampoco. Un chatbot que sigue un árbol de decisión fijo es un diagrama de flujo con un cuadro de texto.
Un agente de IA es un sistema que puede interpretar un objetivo y actuar en consecuencia dentro de un entorno definido. La autonomía dentro de unos límites separa a un agente de un bucle de petición y respuesta. El agente lee el contexto y elige una estrategia, a veces en más de un paso.
¿Dónde se sitúa Artie en este espectro?
No es un agente según esa definición. No navega por la web, no ejecuta código ni encadena llamadas a herramientas de varios pasos. Algolia recupera las páginas antes de que se ejecute el modelo. El modelo las recibe como contexto. Lo que sí hace es interpretar la intención y aplicar las barreras de seguridad por su cuenta. Distingue si una pregunta es técnica o una consulta sobre el portafolio antes de responder. Eso es más que un cuadro de búsqueda con un campo de texto. Y menos que un agente totalmente autónomo que pudiera, por ejemplo, abrir un informe de error a partir de la pregunta de un usuario.
Los redactores técnicos necesitan esta distinción ahora. Entender las herramientas y los agentes de IA forma parte del trabajo. Cuando documentas un producto con IA, necesitas saber en qué punto del espectro se sitúa. Después tienes que explicar a los usuarios qué significa «IA» en ese producto, porque sus expectativas varían.
Cómo funciona la generación aumentada por recuperación
La generación aumentada por recuperación (RAG) alimenta a Artie y a un número creciente de herramientas de documentación con IA. RAG sortea un límite central de los grandes modelos de lenguaje (LLM). Un modelo se entrena con un conjunto de datos fijo. Tu contenido no figura en sus datos de entrenamiento.
Una interacción estándar con un LLM funciona así: el usuario envía una indicación y el modelo genera una respuesta a partir de sus datos de entrenamiento. Eso sirve para conocimiento general y falla ante preguntas de un dominio concreto. Pregúntale a un modelo base por la API de tu producto y o bien inventa una respuesta o bien se niega.
RAG inserta un paso de recuperación entre la pregunta del usuario y la respuesta del modelo. El proceso es el siguiente:
- Procesamiento de la consulta. La capa de recuperación convierte la pregunta del usuario en una incrustación vectorial, una representación numérica de su significado.
- Recuperación. El sistema busca en la base de conocimiento contenido con un significado parecido. Aquí, la base de conocimiento es un índice ya construido de tu documentación. La clasificación depende del significado, a menudo junto con coincidencias de palabras clave. Consultas como «¿cómo configuro la autenticación?» y «configurar credenciales de inicio de sesión» devuelven la misma página de documentación.
- Ensamblaje del contexto. El sistema empaqueta los documentos recuperados, o fragmentos de ellos, en una ventana de contexto junto a la pregunta del usuario y la indicación del sistema. Después el modelo procesa ese paquete.
- Generación. El modelo genera una respuesta basada en el contexto recuperado y no en sus datos de entrenamiento. En un sistema bien ajustado, cita sus fuentes y se ciñe a lo que dicen los documentos recuperados.
- Mermaid (image)
- Mermaid (code)
flowchart TD
A["🔍 Pregunta del usuario"] --> B["Procesamiento de consultas"]
B -->|Incrustación vectorial| C["Recuperación"]
KB[("📚 Base de conocimiento")] -.-> C
C -->|Documentos pertinentes| D["Ensamblaje del contexto"]
D -->|Prompt + contexto| E["Generación"]
E --> F["📄 Respuesta fundamentada"]
La calidad depende del paso 2. Si la capa de recuperación devuelve documentos erróneos o los ordena mal, la capacidad del modelo no ayuda. El modelo redacta una respuesta plausible y bien estructurada a partir de material equivocado. Por eso la segmentación y la elección del modelo de incrustación importan más de lo que la mayoría de los equipos espera. El modelo de generación se lleva el mérito, pero la capa de recuperación determina la calidad.
En el caso de Artie, la base de conocimiento es la documentación de este sitio. Algolia la indexa y la recupera. Artie solo cubre lo que está documentado aquí, lo que lo mantiene dentro del material del propio sitio. El caso práctico explica cómo se resuelve eso. RAG no hace que un modelo sea más inteligente. Hace que sea más responsable, porque cada respuesta se ata a una fuente verificable.
La ingeniería de prompts es redacción técnica
El proyecto me enseñó una lección clara. Una indicación de sistema es un entregable de redacción técnica.
Una indicación de sistema bien redactada contiene las mismas piezas que una guía de estilo. Defines el público. Estableces reglas de tono y voz. Fijas los límites del ámbito: qué debe abordar el sistema y qué no. Escribes instrucciones lo bastante precisas para que una máquina las siga sin criterio humano. Ordenas la información para que las reglas más importantes tengan prioridad.
El trabajo es análisis de audiencia y guía de estilo. También es un plan de contenido.
La transferencia de habilidades es casi uno a uno:
- Análisis de audiencia → Enrutamiento de audiencia. Los redactores técnicos identifican al público y adaptan el contenido, y una indicación de sistema hace lo mismo con una IA. La indicación de Artie separa a los usuarios técnicos de los reclutadores, igual que un sitio de documentación bien estructurado separa los perfiles de lectores.
- Guía de estilo → Calibración del perfil. Todo equipo de documentación tiene directrices de voz y tono. Una indicación de sistema es una guía de estilo para una IA. Ajusta el tono por audiencia y exige un enlace a la fuente en cada afirmación.
- Arquitectura de la información → Jerarquía de instrucciones. Los redactores técnicos saben que el orden y la estructura afectan a la comprensión. La ubicación de una instrucción cambia el grado en que el modelo la cumple.
- Documentación de casos límite → Diseño de barreras. Una buena documentación cubre la acción inesperada con una guía clara. Un buen diseño de indicaciones cubre al usuario que intenta romper el sistema.
No todo redactor técnico tiene que convertirse en ingeniero de prompts. La disciplina toma prestadas habilidades que los redactores técnicos desarrollan durante décadas. Si sabes redactar un documento claro, estructurado y adaptado al público, aportas más a este trabajo de lo que crees.
Las barreras de seguridad son un problema de lenguaje
La gente trata la seguridad de la IA como un problema técnico: límites de peticiones, inicios de sesión, controles de acceso. Todo eso importa. En un chatbot público, buena parte de lo que atacan los atacantes es lingüístico.
La inyección de indicaciones ocurre cuando un usuario anula la indicación del sistema. Un ejemplo habitual es la frase «ignora todas las instrucciones anteriores».
La inyección de indicaciones usa palabras para sortear controles basados en palabras. La defensa consiste en escribir reglas lo bastante claras como para que un atacante no pueda convencer al modelo de saltárselas.
El listado de los diez riesgos principales para aplicaciones de LLM del Open Worldwide Application Security Project (OWASP) sitúa la inyección de indicaciones como el riesgo principal. Lee la lista y verás cuántos riesgos son, en el fondo, problemas de lenguaje:
- Gestión inadecuada de la salida (lo que el modelo produce)
- Envenenamiento de datos y modelos (lo que el modelo aprendió del texto)
- Agencia excesiva (lo que la indicación le dice al modelo que puede hacer)
Los ataques son técnicos. Las defensas suelen ser lenguaje natural, escrito en la indicación del sistema.
Eso replantea el trabajo de seguridad para los redactores técnicos. Nadie espera que construyamos sistemas de autenticación. Pero sí podemos escribir las reglas que definen cómo responde una IA. Podemos escribirlas con la precisión suficiente para resistir entradas hostiles.
Qué cambia en el trabajo de documentación
No voy a predecir el futuro de la IA. Sí puedo describir la trayectoria visible ahora y lo que significa para quien documenta software para ganarse la vida.
Los asistentes de documentación con IA pasaron de novedad a expectativa. Los usuarios ya no aceptan una búsqueda estática. Quieren formular una pregunta llana y recibir una respuesta fundamentada, no diez enlaces azules. Los sistemas RAG lo hacen posible hoy. Las herramientas son cada vez más fáciles de adoptar.
¿Te interesa el lado de la infraestructura? La documentación de flujos de eventos y canalizaciones de observabilidad muestra cómo Datadog y Galileo registran las llamadas a modelos.
El papel del redactor técnico se amplía en lugar de reducirse. Alguien tiene que curar la base de conocimiento de la que estos sistemas recuperan. Alguien tiene que escribir las indicaciones de sistema que definen cómo responden y dónde se detienen. Alguien tiene que comprobar si las respuestas coinciden con la documentación. Todo eso es trabajo de redacción y exige criterio sobre cómo consume información la gente.
Los redactores técnicos deberían aprender cómo funcionan los LLM y los sistemas RAG. No tenemos que convertirnos en ingenieros de aprendizaje automático, pero sí participar en las conversaciones sobre productos de IA. Necesitamos conocimiento suficiente del proceso para saber dónde aplica nuestra experiencia y dónde no.
Los redactores técnicos ya escriben para muchos públicos. Estructuran contenido y fijan el ámbito. Prevén el mal uso. Esas habilidades se aplican directamente al trabajo con IA.
La IA no sustituirá a los redactores técnicos. Los modelos mejoran cada año al generar texto, pero alguien sigue decidiendo qué decir, a quién y dentro de qué límites.
Necesitan un editor. Nosotros somos los editores.
Escribir el primer borrador tú mismo también funciona. Pásaselo al agente de IA como corrector y revisor de estilo.
Cómo usas la IA en tu flujo de trabajo es decisión tuya, como cualquier otra herramienta de la que disponemos.
El trabajo no cambia. Cambian las herramientas. El trabajo no va a ninguna parte. Los equipos que prescinden de sus redactores técnicos vuelven a buscarlos.
Lee el caso práctico
Si esta entrada te dio el «por qué importa» y el «cómo funciona», lee el caso práctico. Cubre las decisiones de diseño concretas que hay detrás de Artie:
- Enrutamiento de audiencia
- Fundamentación del conocimiento
- Calibración del perfil
- Barreras de seguridad
- Decisiones que reconsideraría para un despliegue en producción
Cada pieza funciona por su cuenta. Empieza por la que prefieras.