Este artículo de dein.fr argumenta a favor de integrar la documentación directamente en el repositorio de código, una práctica que se vuelve aún más valiosa con la proliferación de agentes de IA. Tradicionalmente, la documentación se ha mantenido separada, alojada en herramientas como Google Docs, Confluence o Notion. Sin embargo, esta separación introduce problemas como el control de versiones inconsistente, la dificultad para mantener la documentación actualizada en sincronía con el código y la complejidad para generar documentación API automáticamente.
La integración en el repositorio soluciona estos problemas. Permite el control de versiones con Git, facilita la búsqueda y actualización de información (por ejemplo, con rg u orgrep), y simplifica la generación automática de documentación API utilizando herramientas como Sphinx, JSDoc o Docusaurus. Además, la documentación integrada puede servir como especificación viva, permitiendo revisiones tempranas y mejorando la comprensión del producto o API. Incluso permite la ejecución de ejemplos de código directamente en la documentación, lo que facilita las pruebas y la validación.
La aparición de agentes de IA ha acelerado la necesidad de esta integración. Estos agentes pueden generar y mantener documentación, reduciendo la carga de trabajo manual. Además, la documentación integrada proporciona un contexto valioso para los agentes, permitiéndoles comprender mejor el código y el sistema. El artículo también destaca la tendencia a que los ingenieros se enfoquen más en la especificación y las directrices, lo que hace que la documentación sea aún más crucial. Finalmente, se aborda la objeción de que la documentación puede volverse obsoleta, argumentando que los agentes de IA pueden ayudar a mantenerla actualizada y alineada con el código. Aunque herramientas como Google Docs siguen siendo útiles para la colaboración activa, la documentación final debería residir en el repositorio para garantizar la coherencia y facilitar la revisión.