Durante los últimos 15 años he trabajado en docenas de proyectos de software, y casi cada vez la documentación fue terrible. Los desarrolladores subestiman la necesidad de documentación porque piensan que ya lo entienden todo. Los gerentes lo subestiman porque suponen que los desarrolladores pueden simplemente leer el código y entender el proyecto en un par de horas. Incluso cuando las personas no subestiman la documentación, a menudo carecen del tiempo y la capacidad para ello.La visión general precisa y actualizada suele estar en la cabeza de los desarrolladores superiores, que ya llevan muchas responsabilidades. Los desarrolladores a menudo añaden comentarios para funciones triviales o describen parámetros cuando nombres o tipos de variables más claros habrían resuelto el problema. ¿Es posible que la documentación sea obsoleta? Sólo , indicando que muchos equipos tratan la documentación como una "formalidad opcional" El 4% de las empresas siempre documenta sus procesos https://www.bptrends.com/bpt/wp-content/uploads/2015-BPT-Survey-Report.pdf/ Al mismo tiempo, tenemos fuertes evidencias de que sin una buena documentación el negocio solo pierde una enorme cantidad de tiempo-dinero: “Documentación insuficiente” citada por el 41% de los desarrolladores como la principal causa de tiempo perdido, con el 69% de los desarrolladores perdiendo más de 8 horas por semana a tales ineficiencias (alrededor de $ 18.5M en productividad perdida anual por cada 1,000 desarrolladores) https://newsletter.getdx.com/p/state-of-developer-experience-2024 La incorporación de un nuevo ingeniero dura de 3 a 9 meses, dependiendo en gran medida de la documentación https://stripe.com/files/reports/the-developer-coefficient.pdf La falta de documentación es un componente importante de la deuda técnica (https://www.informit.com/store/economics-of-software-quality-9780132582209) Un experimento con más de 30 programadores mostró que la falta de documentación causó aproximadamente un 21% más de tiempo dedicado a comprender el código durante las tareas de mantenimiento https://hci.com.au/get-documentation-budget/ Entonces, ¿cuál es la barrera real detrás de una falta tan generalizada de documentación? En el brillante trabajo de Andrew Forward “Documentación de software – Construir y mantener artefactos de comunicación” han hecho una buena investigación en las razones reales. External Factors Influencing Documentation Quality Como puede ver, la falta de tiempo y presupuesto se correlaciona con la frustración de que el esfuerzo de documentación pueda volverse inútil y rápidamente obsoleto. Así que si reducimos el esfuerzo manual y solucionamos el problema de que la documentación se vuelva obsoleta, podemos dar un paso significativo hacia adelante. La comunidad de desarrolladores ya ha introducido enfoques como Javadoc y herramientas similares que generan documentación automáticamente a partir de firmas de código. Por lo tanto, todavía necesitamos documentación bien escrita, actualizada y legible por el hombre. El verdadero desafío es que la documentación no es una entrega única, sino una Incluso si un equipo escribe buenos documentos al principio, el código evoluciona más rápido que los hábitos de documentación. Artefacto viviente Esto significa que la botella no es La documentación, pero . escribiendo Mantenerlo correcto soluciones A quien La IA es realmente buena en combinar patrones simples entre el código y los documentos.Hay algunas buenas soluciones en las que puede automatizar la deriva de la documentación a través de la IA: Merge request rules, pointing agent to existing documentation and changed code base Claude Code documentation agent that keeps project docs up to date with Docusaurus. npx claude-code-templates@latest --agent=documentation/docusaurus-expert --yes Este enfoque funciona bien para: Actualización de descripciones de alto nivel Resumir el código de intención Reescribir frases obsoletas Restaurar el contexto narrativo perdido Sin embargo, el AI tiene limitaciones claras: Se lucha para detectar inconsistencias estructurales (por ejemplo, env var no documentado, puertos, banderas CLI, banderas de características). Puede halucinar, especialmente cuando los documentos son incompletos o ambiguos. No produce controles deterministicos rastreables - cada carrera puede generar un resultado ligeramente diferente. No puede decir de manera fiable lo que es importante y lo que es ruido sin conocimiento del dominio. En otras palabras, AI puede ayudar Sin embargo, no es fiable como una . rewrite and improve text source of truth validator Controles estáticos Herramientas como Aborda este problema tratando la documentación como algo que debe ser monitoreado continuamente, al igual que la calidad del código o la deriva de la infraestructura. Funciona puramente algorítmicamente para no verse afectado por las alucinaciones, aunque, por supuesto, todavía son posibles falsos positivos. Duque Ducku trabaja extrayendo señales estructurales de su repositorio - variables ambientales, rutas de API, puntos de entrada de servicio, importaciones de módulos, estructura de directorio, claves de configuración - y comparándolas con lo que se hace referencia en sus READMEs y wiki. Capacidades actuales Verificación de la presencia de entidades: Detecta cuando las variables de entorno, claves de configuración, puertos, rutas de API o nombres de scripts aparecen en la documentación pero no en el código (y viceversa). Cobertura de entidades paralelas: Identifica grupos de elementos similares (servicios, empleos ETL, manejadores de lambda, comandos CLI) y señala adiciones no documentadas. Análisis de módulos muertos: Detecta los archivos que no se importan / usan en ningún lugar, ya sea puntos de entrada que merecen explicación o artefactos obsoletos. Verificación de integridad de URL: Detecta enlaces rotos o desactualizados a recursos internos o externos. Magia y consistencia del estilo: higiene básica que normalmente se ignora. Esto ya es suficiente para reducir una gran parte del flujo de documentación silenciosa en proyectos reales. Conclusión La documentación no falla porque los ingenieros son descuidados. que lo mantiene alineado con el sistema que describe. El código tiene pruebas. La infraestructura tiene detección de drift. CI tiene puertas de política. La documentación, en la mayoría de equipos, no tiene nada. no feedback loop La IA puede mejorar la expresión y restaurar el contexto, pero no puede decir de manera fiable si la documentación es correcta. Las verificaciones estáticas, por otro lado, pueden validar el alineamiento factual, pero no pueden explicar la intención o la lógica del dominio. correct Ambos juntos pueden traer lo que necesitas.
