Cómo mantener la documentación técnica al día con IA
Cambia el script de despliegue, pero el manual operativo todavía indica el comando anterior. La siguiente persona que lo sigue pierde tiempo buscando qué falló. Un cambio pequeño en el código terminó creando un problema de documentación.
Un agente de IA puede comparar un cambio con los documentos afectados y preparar una actualización. Lo útil es que un ingeniero pueda revisar ese borrador con facilidad y consultar el código y las decisiones que lo respaldan. Alguien sigue siendo responsable del cambio.
Del cambio en el código a la actualización
Empieza con un evento concreto, como la integración de un pull request que modifica una API o una opción de configuración. Dale al agente acceso al repositorio y a los documentos pertinentes, y pídele que:
- Identifique las instrucciones o los ejemplos afectados. Una opción de configuración eliminada, por ejemplo, puede seguir apareciendo en la guía de instalación.
- Proponga una actualización y cite el commit, la especificación o el ticket que la respalda. Si las fuentes no alcanzan para confirmar algo, debe señalarlo.
- Ejecute la compilación de la documentación, la comprobación de enlaces y las pruebas de los ejemplos en un entorno de pruebas aislado.
- Abra un pull request con el texto propuesto, las comprobaciones realizadas y las preguntas pendientes.
La persona que mantiene esa parte del sistema revisa la actualización antes de integrarla. La revisión ayuda a detectar errores, pero no garantiza que la documentación sea correcta. Hay que probar los ejemplos y comprobar que las instrucciones operativas correspondan al entorno donde se usarán.
Las notas de versión pueden seguir un proceso parecido: preparar un resumen de los cambios integrados, enlazar los tickets correspondientes y pedir al equipo que revise qué necesita saber el usuario.
Conserva las razones de una decisión
Un agente puede resumir una conversación de arquitectura que quedó registrada. Si las fuentes no explican por qué el equipo eligió un diseño, debe pedir ese contexto. Una explicación convincente no demuestra cuál fue el razonamiento del equipo.
Un registro de decisión de arquitectura cumple una función distinta de una guía de instalación: conserva una decisión tomada en un momento concreto. Si el diseño cambia, agrega una nueva decisión e indica que reemplaza a la anterior, sin borrar su historia.
Otras tareas de mantenimiento para probar
El mismo proceso puede ayudar a actualizar una dependencia: preparar el cambio, enlazar las notas de versión, identificar el código afectado y adjuntar los resultados de las pruebas. Ante un reporte de error, el agente puede intentar reproducirlo y proponer una prueba que falle para que el equipo la revise.
Un inventario de sistemas necesita más que acceso al repositorio. Puede requerir registros de despliegue y una lista actualizada de responsables. Define esas fuentes para que el agente pueda señalar información faltante.
Empieza con un documento que puedas comprobar
Elige un repositorio y un tipo de documento cuyos ejemplos se puedan probar de forma segura, como una guía de instalación local. Un manual operativo también puede servir, pero sus comandos pueden modificar infraestructura o datos. Pruébalos en un entorno aislado con los permisos adecuados; tener acceso al documento no debería dar permiso para ejecutarlos en producción.
Revisen juntos las primeras actualizaciones propuestas. Comprueben si encontraron omisiones reales, si las fuentes respaldan el texto y cuánto hubo que corregir. Amplía el alcance cuando esos borradores le ahorren trabajo al equipo. Si generan más trabajo de revisión, ajusta el evento que los activa, el contexto o las comprobaciones antes de agregar más documentos.