El proyecto de código abierto Docsy, creado por Google para construir sitios de documentación mediante el generador de sitios estáticos Hugo, pasa a la Linux Foundation en un momento en que la documentación técnica se ha convertido en una fuente directa para los agentes de inteligencia artificial, y no solo para los desarrolladores.
Erin McKean, ingeniera de relaciones con desarrolladores en Google y miembro del comité directivo de Docsy, anunció el paso durante una conferencia pronunciada el miércoles en la cumbre europea de código abierto de la Linux Foundation, celebrada en Praga. El traslado se debe en parte a la difusión de Docsy dentro del ecosistema de proyectos vinculados a la fundación; a finales de 2024, alrededor de 2.200 proyectos lo utilizaban, entre ellos proyectos de la Cloud Native Computing Foundation como Kubernetes, OpenTelemetry, gRPC y Jaeger.
Un proyecto de documentación orientado a una audiencia automatizada
Docsy se anunció por primera vez en 2019. Es una plantilla de código abierto destinada a la documentación técnica que puede utilizarse con proyectos abiertos o privados. Sin embargo, los cambios recientes se centran en la forma en que las herramientas de inteligencia artificial acceden al contenido y en el formato de las instrucciones que estas herramientas necesitan para ejecutar tareas relacionadas con los proyectos.
Desde la versión 0.15.0, publicada en mayo, Docsy puede generar una versión Markdown de cada página además de la versión HTML habitual. También puede generar un archivo llms.txt que proporciona un índice del contenido del sitio. Ambas funciones son opcionales y experimentales.
En la versión 0.16.0, publicada en julio, se añadió una guía de actualización redactada para que un asistente automatizado pueda seguirla, con la inclusión de requisitos, pasos y procesos de verificación. Por su parte, la versión 0.17.0, publicada en agosto, añadió una directiva oculta en la parte superior de cada página para los usuarios que activan llms.txt, con el fin de dirigir a los agentes visitantes al índice del sitio. Esta función también sigue siendo experimental.
¿Qué cambia en la práctica?
Docsy transforma parte de la tarea de mejorar la documentación: pasa de limitarse a dar formato a páginas para la lectura humana a organizar el contenido de manera que los modelos y agentes puedan encontrarlo, entenderlo y seguirlo. Para los proyectos que dependen de colaboradores o usuarios externos, esto podría significar dirigir las herramientas de inteligencia artificial a una versión más clara de las instrucciones, en lugar de dejar que las deduzcan de las páginas HTML públicas.
McKean afirma que una documentación mejor puede reducir las preguntas rutinarias que llegan a los responsables de mantenimiento, porque las respuestas pasan a estar disponibles para los usuarios antes de que intervenga un maintainer. Es un posible beneficio operativo para los proyectos, pero no significa por sí mismo que los agentes comprendan correctamente el contenido ni que la documentación se vuelva precisa automáticamente.
El siguiente paso: medir la legibilidad para los agentes
El equipo de Docsy trabaja en lo que denomina AF documentation scores, es decir, puntuaciones sobre la adecuación de la documentación para los agentes. El objetivo es proporcionar a los responsables de mantenimiento una métrica para evaluar la capacidad de las herramientas de inteligencia artificial de descubrir, navegar y consumir la documentación, en lugar de limitarse a hacer suposiciones.
La fuente todavía no aclara la forma que tendrá esta métrica, sus criterios definitivos ni la fecha de lanzamiento. Además, las funciones de Markdown y llms.txt, así como las directivas relacionadas, son opcionales y experimentales, por lo que su impacto práctico seguirá dependiendo de que los proyectos las adopten y de la calidad del contenido original que produzcan.