Documentación automática con LLM: cuándo aporta y cuándo molesta
Actualizado: 2026-05-03
Desde que los modelos grandes de lenguaje entraron en las herramientas de desarrollo de uso diario, la promesa de documentación automática ha pasado de consigna de marketing a producto real incorporado en Copilot, Claude Code, Cursor y multitud de integraciones más pequeñas. Con dos años de uso masivo acumulado, tenemos suficiente material para valorar con calma dónde aporta valor real, dónde resulta ruido y qué patrones conviene seguir si queremos que la documentación generada envejezca bien en lugar de convertirse en otra capa de deuda técnica.
Puntos clave
- La documentación automática aporta valor claro para referencia de API sobre código bien tipado: el modelo traduce intención ya presente, no la inventa.
- Las cadenas de documentación en línea masivas para código de negocio privado son el caso donde más daño hace: prosa obvia que contamina la lectura sin aportar contexto real.
- Sin bucle de mantenimiento no vale la pena crear documentación generada: si nadie la regenera cuando cambia el código, diverge silenciosamente y transmite falsa confianza.
- El modelo produce el primer 70% estructurado; el 30% restante — las decisiones de diseño, los casos límite, el porqué — sigue siendo trabajo humano.
- Cuatro categorías claras: docstrings en línea, generadores de README, generadores de referencia de API y asistentes de diagramación. Cada una tiene una relación distinta con el valor real.
Qué significa documentación automática en la práctica
El espacio se ha expandido mucho desde las primeras versiones. Hoy conviven al menos cuatro categorías distintas:
- Generadores de comentarios en línea — escribes una función y el asistente propone descripción, parámetros y tipo de retorno.
- Generadores de README y páginas de guía — leen un repositorio completo, deducen su propósito y proponen documentación de primer nivel.
- Generadores de referencia de API — consumen código, contratos OpenAPI o esquemas y producen páginas estructuradas con ejemplos.
- Asistentes de diagramación — producen descripciones textuales o diagramas mermaid a partir de la estructura del código o los servicios.
Las dos primeras son las más comunes y también donde se concentra la mayoría de las críticas. La tercera ha madurado bastante con integraciones directas en herramientas como Stainless, Mintlify o Scalar. La cuarta está todavía en fase temprana pero creciendo rápido.
Donde funciona sin reservas
Hay un caso de uso donde la documentación automática aporta valor sin peros importantes: la referencia de API de bibliotecas y servicios bien tipados. Cuando tienes un esquema OpenAPI completo, unos tipos bien declarados o una superficie de código pequeña y estable, los modelos producen documentación coherente, precisa y mantenible. El trabajo humano pasa de escribir la descripción inicial a revisar y refinar las aristas difíciles.
Esto funciona porque la tarea está bien acotada: el modelo no tiene que inventar intención, solo expresarla en prosa clara. La información ya está en el código y en los tipos; el modelo la traduce. Cuando la superficie cambia, el proceso se puede repetir y la documentación se mantiene al día sin intervención manual significativa. Proyectos como Stripe, Vercel o Cloudflare usan pipelines similares desde hace tiempo y los resultados son sólidos.
El segundo caso con beneficios claros es la documentación de migraciones y cambios. Dado un diff significativo entre dos versiones, un modelo puede producir un primer borrador de notas de lanzamiento o de guía de migración que después un humano pule. El borrador ahorra un trabajo real y tedioso que de otra forma consumiría horas.
Donde molesta más que ayuda
El caso contrario, donde la documentación automática tiende a degradar la calidad del proyecto, es el de las cadenas de documentación en línea para código privado de aplicaciones empresariales. Cuando un desarrollador acepta descripciones generadas para cada función de un código base de negocio, el resultado habitual es un mar de prosa obvia que no aporta nada sobre la intención real y acaba contaminando la lectura del código. “Esta función obtiene el usuario por identificador” delante de una función que literalmente hace eso no informa a nadie.
El problema es doble:
- La documentación verdaderamente útil describe el porqué: las decisiones de diseño, las contraindicaciones, los casos límite. Nada de eso puede inferir un modelo leyendo solamente el código.
- El ruido generado compite por la atención con los comentarios útiles que sí existen, y los diluye.
El segundo patrón problemático son los archivos README generados en frío por lotes para repositorios internos. Son largos, cubren secciones que nadie usa (licencia, contribuciones, código de conducta copiado literal) y presentan la herramienta con frases que suenan a folleto corporativo. Cuando entra un compañero nuevo al equipo y abre el README esperando orientación sobre cómo arranca el servicio en su portátil, se encuentra con un documento corporativo genérico.
El problema del envejecimiento
Un matiz que no se discute suficiente es cómo envejece la documentación automática. Cuando un humano documenta un sistema, registra estado en un momento específico pero también intención: por qué se tomó una decisión, qué alternativas se descartaron. Esa información tiene valor arqueológico real incluso cuando el código evoluciona. La documentación generada a partir del código presente tiene el problema inverso: si no se regenera, envejece peor que la escrita a mano porque nadie siente responsabilidad sobre ella.
La práctica que funciona es integrar la generación en el ciclo de publicación: cada vez que se corta una versión, se regenera la referencia de API desde el contrato, se revisa y se publica. Si falta ese mecanismo, la documentación queda como foto fija que diverge silenciosamente del sistema real. Es el peor escenario posible porque transmite falsa confianza: parece mantenida pero no lo está.
Pautas prácticas que funcionan
Del material acumulado emergen unas pocas pautas que generalizan bien:
- No generar documentación sin bucle de mantenimiento: si no hay un proceso que regenere cuando el código cambia, no merece la pena crearla.
- Distinguir documentación de referencia de documentación de intención: la primera se presta a generación, la segunda casi nunca.
- Auditar la salida antes de comprometerla: un modelo puede inventar parámetros inexistentes, describir comportamientos contrarios al código o inferir limitaciones erróneas; una lectura humana los detecta en minutos pero una vez publicados quedan como información oficial.
- Tratar la documentación generada como borrador, no como producto final: el modelo convierte una página en blanco en un 70% estructurado; el 30% restante sigue siendo trabajo humano.
Este último punto conecta directamente con el enfoque que describimos en grafos de conocimiento con LLM: la extracción automática aporta estructura inicial, pero la calidad exige revisión humana de las relaciones y entidades extraídas.
Cómo pensar la decisión
Mi lectura es que la documentación automática es una palanca real cuando se aplica a problemas estructurados con contratos claros, pero se vuelve una trampa cuando se aplica indiscriminadamente con la esperanza de resolver la documentación de todo el sistema de un golpe. El error más común es confundir la capacidad de generar texto con la capacidad de documentar: documentar bien exige saber qué decir y qué omitir, y esa decisión sigue siendo humana.
La conclusión práctica: usar la generación para referencia de APIs, notas de lanzamiento, guías de migración y primer borrador de onboarding, sí, con revisión posterior. Usarla para cadenas de documentación en línea masivas, archivos README de repositorios internos o documentación de arquitectura, casi nunca sin una edición profunda posterior. Los equipos que distinguen estos dos usos publican mejor documentación con menos esfuerzo; los que no lo hacen acumulan ruido que cuesta limpiar después y que, paradójicamente, degrada la calidad percibida del proyecto frente a simplemente no documentar esas partes.
