Generar documentación a partir del código: en qué acierta y en qué falla la IA

por Fraser Hardy

Un editor de código y la ventana de una app en ejecución alimentan un borrador de artículo de ayuda con pasos numerados y una captura de pantalla, que un revisor marca como comprobado

Apunta un modelo a un repositorio, pídele un centro de ayuda y te lo dará. Parecerá terminado. Hasta que leas el artículo cuatro y veas que cuenta a tus clientes cosas sobre PlanTier.PRO_LEGACY y una pantalla en /admin/impersonate.

Entonces, ¿puede la IA generar documentación a partir del código? Sí, y los borradores son útiles. La IA es buena para encontrar todas las funciones, acertar con los nombres de los botones y producir una primera versión coherente. Pero, tal como sale del modelo, falla de forma sistemática en tres cosas: filtra jerga interna, documenta pantallas que tus usuarios no pueden ver y describe el código en lugar de la tarea que el usuario intenta hacer. La solución es fundamentar los borradores en la app en ejecución y hacer que una persona revise todo antes de publicarlo.

Aquí explicamos por qué y cómo montarlo para que el resultado merezca publicarse.

Dos tipos muy distintos de «documentación a partir del código»

Cuando la gente busca esto, se refiere a dos cosas y conviene separarlas.

Documentación de referencia para desarrolladores. Referencias de API, documentación de SDK, firmas de funciones. Es un problema en su mayor parte resuelto y no necesita IA en absoluto. Herramientas como TypeDoc, Sphinx autodoc, Javadoc y las de OpenAPI como Swagger UI leen tu código o tu especificación y producen páginas de referencia de forma determinista. Son aburridas y fiables, que es justo lo que quieres de una documentación de referencia.

Documentación de usuario. Artículos de un centro de ayuda para personas que nunca verán tu código: «cómo exporto mis facturas», «cómo añado a un compañero». Es la parte difícil, y es donde los generadores de documentación con IA son ahora realmente útiles y realmente arriesgados.

Esta entrada trata del segundo tipo. Si necesitas un README o comentarios de código, tu asistente de programación ya lo hace lo bastante bien.

Lo que la IA hace bien al generar documentación de usuario a partir del código

Hay que reconocer lo que es mérito suyo. Un modelo que lee una base de código es mejor que una persona en algunas tareas concretas.

Lo encuentra todo

Las personas escriben la documentación de memoria, y la memoria olvida funciones. La importación de CSV que alguien construyó hace ocho meses. El atajo de teclado. El ajuste que solo aparece en el plan de equipo. Un modelo que lee tu archivo de rutas, tus componentes de navegación y tus formularios produce un inventario completo, y solo ese inventario ya justifica el ejercicio. La mayoría de los centros de ayuda tienen lagunas que nadie conoce.

Acierta con los nombres exactos

El texto de los botones está ahí mismo en el código: "Export CSV", "Send invite". Un modelo lo citará tal cual, mientras que una persona escribe «haz clic en el botón de exportar» y deja al lector adivinando.

Detecta límites y reglas

Las reglas de validación viven en el código. Una longitud máxima para el nombre de un proyecto, un límite de tamaño de archivo, una comprobación de rol que deja un botón en gris. Son justo los detalles que generan tickets de soporte («¿por qué no puedo guardar esto?») y justo los detalles que una persona redactora no conoce.

En qué falla la IA al generar documentación a partir del código

Esta es la parte que la mayoría de las herramientas no pone en su página de inicio. En mi experiencia, estos fallos aparecen en casi todos los borradores en bruto de la IA.

1. Se cuela la jerga interna

Tu código y tu interfaz usan palabras distintas. La tabla es workspaces, la interfaz dice «Equipo». El enum es PlanTier.PRO_LEGACY, la página de precios dice «Pro». La función se llamó smartRouting internamente durante un año antes de que marketing la bautizara como «Asignación automática».

El modelo lee el código, así que usa palabras del código. Te salen frases como «Crea un nuevo workspace (org) desde la página de Equipos», que confunde a los clientes y además es incorrecta. Peor aún, filtra nombres que nunca pensaste hacer públicos.

2. Documenta pantallas que tus usuarios no pueden ver

Un modelo ve una ruta y escribe un artículo sobre ella. No tiene ni idea de que:

Así que escribe artículos de ayuda para todos ellos. En el mejor de los casos, los clientes buscan pantallas que no existen para ellos y te escriben. En el peor, has publicado tu hoja de ruta o una guía de tu herramienta de suplantación de administrador.

3. Describe el código en lugar de la tarea del usuario

Esta es la más sutil y la más común. Un modelo explica lo que hace el código, porque es lo que tiene delante. A los usuarios no les importa lo que hace el código. Quieren conseguir algo.

Comparación lado a lado: a la izquierda, un borrador de IA que explica el componente InvoiceExport, su endpoint de API y una ruta de administración; a la derecha, una reescritura titulada «Descarga tus facturas» con tres pasos sencillos y una captura de pantalla

La versión de la izquierda es exacta. También es inútil para alguien cuyo contable acaba de pedirle las facturas del último trimestre. La versión de la derecha parte del objetivo, usa las palabras que aparecen en pantalla y muestra dónde hacer clic. El marco Diátaxis traza bien esta línea: una guía práctica sirve a un objetivo, una referencia describe la maquinaria. Los borradores en bruto de la IA derivan hacia la referencia incluso cuando pediste una guía práctica.

4. Adivina con aplomo comportamientos que el código no resuelve

Gran parte de lo que experimentan los usuarios no lo decide solo el código. Que un correo de confirmación se envíe de verdad depende de la configuración. Cómo se ve una página depende de los datos que contiene. Tu política de reembolsos, tu horario de soporte y lo que pasa con los datos tras la cancelación normalmente no están en el repositorio.

Un modelo rellena esos huecos con suposiciones verosímiles escritas con el mismo tono seguro que todo lo demás. Eso es lo peligroso: las frases erróneas no se distinguen de las correctas.

Por qué importa basar la documentación en la app en ejecución

El código te dice lo que puede existir. La app en ejecución muestra lo que un usuario ve de verdad.

Si generas documentación solo a partir del código, estás documentando una teoría de tu producto. Ejecuta la app, inicia sesión como un usuario normal en un plan normal y la mayoría de los problemas anteriores se reducen:

Puedes hacerlo tú mismo con una herramienta de automatización del navegador. Un script mínimo de Playwright que inicia sesión como usuario de demostración y captura una página para un artículo sería así:

// docs/capture/billing.spec.ts
import { test } from '@playwright/test';

test('capture billing page for the invoices article', async ({ page }) => {
  await page.goto('http://localhost:3000/login');
  await page.getByLabel('Email').fill('docs-demo@example.com');
  await page.getByLabel('Password').fill(process.env.DOCS_DEMO_PASSWORD!);
  await page.getByRole('button', { name: 'Sign in' }).click();

  await page.goto('http://localhost:3000/settings/billing');
  await page.screenshot({ path: 'docs/img/download-invoices-step-1.png' });
});

La documentación de capturas de pantalla de Playwright explica las capturas de un solo elemento y de página completa. Lo difícil no es el script, sino tener datos de demostración sembrados que parezcan reales y un inicio de sesión que funcione en CI. Repasamos toda la configuración en cómo crear capturas de pantalla de producto automáticamente.

Por qué la revisión humana sigue sin ser opcional

Incluso con una buena base, alguien que conozca el producto tiene que leer cada artículo antes de que salga. No echarle un vistazo. Leerlo.

Esta es la lista de comprobación que le daría a un revisor:

  1. Las palabras coinciden con la interfaz. Cada nombre de función, botón y elemento de menú es lo que ven los clientes, no lo que dicen los ingenieros.
  2. Cada pantalla es accesible. Un cliente en el plan al que va dirigido el artículo puede llegar de verdad hasta allí. Las funciones propias de un plan lo indican.
  3. Parte de la tarea. El título es algo que un usuario escribiría en el buscador. El primer paso es un clic, no un párrafo de contexto.
  4. Las políticas son reales. Todo lo relativo a dinero, datos, cancelaciones u horarios de soporte viene de ti, no del modelo.
  5. Nada sin publicar. Sin funciones beta, sin herramientas internas, sin nombres que marketing no haya anunciado.

Revisar un borrador decente es mucho más rápido que escribir desde una página en blanco, que es justo la idea. Pero es el paso que convierte un borrador verosímil en documentación que puedes respaldar. Si te lo saltas, estás publicando las suposiciones del modelo con el nombre de tu empresa.

Un proceso de seis pasos para generar documentación a partir del código: leer el código, filtrar las pantallas de administración y protegidas por flags, ejecutar la app y capturar pantallas, redactar artículos basados en tareas, revisión humana y, por último, publicar y volver a comprobar cuando cambie el código

Un flujo casero que puedes ejecutar con tu asistente de programación

No necesitas un generador de documentación con IA específico para obtener la mayor parte del valor. Con Cursor, Claude Code, Copilot o similares:

1. Pide un inventario, no artículos. Algo como:

List every user-facing feature in this app. For each one give:
- the route or screen where a user finds it
- the exact button/menu labels involved
- any plan, role or feature-flag check guarding it
Do not write documentation yet.

2. Poda a mano. Tacha las rutas de administración, las herramientas internas, las betas protegidas por flags y el código muerto. Lleva diez minutos y evita los peores fallos.

3. Dale un glosario. Una lista corta que asocie los términos del código con los de la interfaz (workspace → Equipo, PRO_LEGACY → Pro). Pégala en cada instrucción de redacción.

4. Redacta una tarea por artículo. Pide una guía práctica escrita para un usuario no técnico, usando solo textos del inventario, que empiece por el objetivo y que marque con [CHECK] cualquier frase de la que no esté seguro.

5. Recorre la app y haz capturas. Sigue tú mismo cada artículo. Corrige lo que esté mal y añade capturas.

6. Revisa con la lista de comprobación anterior y publica. En cuanto a la estructura, cómo escribir artículos de centro de ayuda que la gente realmente use incluye una plantilla que encaja muy bien aquí.

La debilidad del flujo casero es el paso 7, que todavía no existe: darte cuenta de cuándo el cambio de código de la semana que viene deja mal el artículo doce. Es un problema aparte, que se aborda en cómo mantener la documentación al día.

Cómo lo resuelve Ellie Docs

Hemos creado Ellie Docs en torno a los fallos descritos arriba, así que veamos cómo encaja.

Lee tu repositorio y mapea las funciones y las pantallas de cara al usuario, y después redacta un centro de ayuda organizado según lo que hacen los usuarios.

El árbol de contenido de Ellie Docs mostrando un centro de ayuda redactado a partir del código, con secciones como Primeros pasos y Mejora las respuestas de Ellie, cada una con artículos nombrados por tarea

Ejecuta tu app en un entorno aislado y captura pantallas reales del producto con la sesión iniciada, que se colocan en los artículos. Cada artículo muestra en qué funciones se basa, de modo que, cuando esas funciones cambian en el código, Ellie sabe que el artículo puede verse afectado.

El editor de artículos de Ellie Docs mostrando un artículo publicado con una captura de pantalla de la app tomada automáticamente, además de un panel «Basado en» con las funciones vinculadas y un panel de Capturas con las imágenes tomadas

En cada PR fusionado, comprueba qué artículos toca el cambio y propone ediciones como un diff que aceptas o descartas. Cuando redacta tu registro de cambios a partir de los PR fusionados, retiene las entradas del trabajo sin publicar o protegido por flags. Nada se publica por sí solo. Publicas tú.

Una actualización sugerida de un artículo de ayuda tras un pull request, mostrada como un diff en rojo y verde que sustituye un paso obsoleto por los nuevos pasos de los ajustes de Disponibilidad, con los botones Descartar y Aceptar

A veces sigue equivocándose. No puede conocer tus políticas y, de vez en cuando, elegirá una palabra del código en lugar de una de la interfaz. Por eso cada borrador y cada sugerencia pasan por ti. Si trabajas con una app creada con un generador de IA, la guía para documentar una app creada con vibe coding cubre las dificultades adicionales.

Algunas preguntas habituales

¿Existe un generador de documentación con IA gratuito? Tu asistente de programación más el flujo casero de arriba no cuesta nada extra. Ellie Docs también tiene un plan gratuito sin tarjeta, si prefieres que se encarguen por ti de las capturas y del seguimiento de actualizaciones.

¿Puede la IA generar documentación de API sin una especificación OpenAPI? Puede, leyendo tus controladores de rutas. Si ya tienes una especificación, usa herramientas estándar como Swagger UI o Redoc; es determinista y gratuito. Ellie Docs genera una referencia de API a partir del código sin especificación en su plan Growth, lo que ayuda si nunca escribiste una.

¿Debo dejar que la IA publique la documentación automáticamente? No. Deja que redacte y proponga. Una persona que conozca el producto debería aprobar todo lo que vayan a leer los clientes, especialmente lo relativo a facturación o datos.

¿Será precisa la documentación escrita por IA? Tan precisa como la base y la revisión que la respalden. Solo a partir del código, espera un borrador útil con errores cometidos con aplomo. Con base en la app en ejecución y revisada por alguien que conozca el producto, puede ser mejor que lo que escribe a mano la mayoría de los equipos, sobre todo porque cubre funciones que las personas olvidaron.

Si quieres borradores basados en tu app real, con capturas y sugerencias PR a PR que tú apruebas, prueba Ellie Docs gratis. Conecta un repositorio y revisa hoy mismo tu primer centro de ayuda redactado.