30. Control de versiones de la documentación y relación con el código fuente
30.1 Introducción
La documentación técnica cambia junto con el software. Cuando se agregan funcionalidades, se modifican APIs, cambian configuraciones o se corrigen errores, la documentación relacionada también debe evolucionar. El control de versiones permite administrar esa evolución de manera ordenada.
Versionar documentación significa conservar historial de cambios, relacionar documentos con versiones del sistema, revisar modificaciones y recuperar estados anteriores. Esto es especialmente útil cuando la documentación vive cerca del código fuente.
En este tema veremos cómo controlar versiones de documentos, cuándo ubicarlos en el repositorio, cómo relacionarlos con cambios de código, cómo revisar documentación y cómo manejar documentación por versión de producto.
30.2 Por qué versionar documentación
Sin control de versiones, puede ser difícil saber si un documento está actualizado, quién lo modificó, cuándo cambió o qué versión del sistema describe. Esto genera dudas, especialmente en documentación de instalación, API, arquitectura, pruebas y despliegue.
El control de versiones permite comparar cambios, revisar propuestas antes de publicarlas, asociar documentación con releases y revertir errores. También mejora la responsabilidad compartida: los cambios quedan visibles.
30.3 Documentación y código versionados juntos
La imagen muestra documentación y código fuente versionados en conjunto: ramas, commits, revisión, historial, releases y publicación. La idea es que los cambios técnicos y los cambios documentales puedan avanzar coordinados.
30.4 Documentación en el repositorio
Guardar documentación en el mismo repositorio que el código es útil cuando ambos cambian juntos. README, guías de instalación, documentación de API, decisiones técnicas, diagramas como código y pruebas suelen beneficiarse de esta cercanía.
Cuando un cambio de código requiere actualizar documentación, ambos cambios pueden revisarse en la misma solicitud. Esto reduce el riesgo de olvidar documentos afectados.
30.5 Documentación fuera del repositorio
No toda documentación debe estar en el repositorio. Manuales para usuarios finales, documentación comercial, contenidos de capacitación o información con permisos especiales pueden vivir en otros sistemas.
La decisión depende de audiencia, seguridad, flujo de edición y frecuencia de cambios. Lo importante es mantener trazabilidad: si una página externa describe una versión o funcionalidad, debe existir forma de saber cuándo actualizarla.
30.6 Commits y mensajes de cambio
Cuando la documentación se versiona, los cambios deben tener mensajes claros. Un mensaje como "actualiza docs" puede ser insuficiente. Es mejor indicar qué se actualiza y por qué: "actualiza guía de instalación para nueva variable de entorno".
Los mensajes ayudan a entender historial. Esto es útil cuando se necesita saber cuándo cambió un procedimiento, una API o una decisión técnica.
30.7 Ramas y revisiones
Las ramas permiten preparar cambios sin afectar la versión principal. Esto sirve tanto para código como para documentación. Una modificación de API puede incluir código, pruebas y documentación en la misma rama.
La revisión por pares permite detectar errores, inconsistencias y omisiones. Un cambio técnico debería revisar si la documentación relacionada también cambió.
30.8 Documentación por versión
Cuando existen varias versiones activas de un producto, puede ser necesario mantener documentación por versión. Esto es común en APIs, productos instalables, bibliotecas, frameworks o sistemas con clientes en versiones distintas.
La documentación debe dejar claro qué versión describe. Si un usuario consulta instrucciones de una versión diferente, puede ejecutar pasos incorrectos o usar funciones inexistentes.
30.9 Releases y notas de versión
Una release puede incluir cambios funcionales, técnicos y documentales. Las notas de versión resumen qué cambió, qué se corrigió, qué se agregó, qué se eliminó y qué acciones deben realizar usuarios u operación.
Las notas de versión conectan el control de versiones con la comunicación. Ayudan a entender el impacto de una entrega sin revisar todos los commits.
30.10 Trazabilidad con cambios de código
La documentación debe relacionarse con cambios de código cuando corresponde. Si se modifica un endpoint, debe actualizarse la documentación de API. Si cambia una migración, debe actualizarse la guía de despliegue. Si cambia una regla, deben revisarse documentación funcional y pruebas.
Esta trazabilidad puede gestionarse mediante checklist de revisión, enlaces en solicitudes de cambio, tareas relacionadas o normas de definición de terminado.
30.11 Conflictos y edición colaborativa
Cuando varias personas editan documentación, pueden aparecer conflictos. Los formatos de texto plano como Markdown suelen resolver conflictos mejor que archivos binarios. Esto es una ventaja para documentación como código.
Para reducir conflictos, conviene dividir documentos largos en secciones, usar archivos separados por tema y evitar cambios de formato innecesarios.
30.12 Automatización
El control de versiones permite automatizar validaciones y publicación. Por ejemplo, se pueden revisar enlaces rotos, generar un sitio estático, publicar documentación al fusionar cambios o validar una especificación de API.
La automatización ayuda a mantener calidad, pero no reemplaza la revisión humana del contenido.
30.13 Tabla de prácticas
| Práctica | Beneficio | Ejemplo |
|---|---|---|
| Documentación en repositorio | Cambios técnicos y documentales juntos. | Actualizar API y especificación en la misma rama. |
| Revisión por pares | Detecta errores antes de publicar. | Revisar guía de despliegue con operación. |
| Versiones de documentación | Evita mezclar instrucciones de versiones distintas. | Documentación para API v1 y v2. |
| Publicación automática | Reduce pasos manuales y desactualización. | Generar sitio al aprobar cambios. |
30.14 Documentación sensible
El control de versiones conserva historial. Por eso, no deben subirse secretos, claves, datos personales reales o información sensible que no debería quedar guardada. Eliminar un secreto del archivo actual no siempre lo elimina del historial.
La documentación versionada debe usar ejemplos seguros y describir dónde se configuran secretos sin exponerlos.
30.15 Definición de terminado
Una forma práctica de mantener documentación actualizada es incluirla en la definición de terminado. Una tarea no se considera completa hasta revisar si afecta documentación y actualizarla cuando corresponde.
Esto puede incluir README, API, manuales, pruebas, despliegue, arquitectura o decisiones técnicas. No todas las tareas requieren cambios documentales, pero todas deberían considerarlo.
30.16 Errores frecuentes
Al versionar documentación suelen aparecer estos errores:
- No indicar qué versión del sistema describe un documento.
- Actualizar código sin actualizar documentación relacionada.
- Guardar documentación en archivos binarios difíciles de revisar.
- Subir secretos o datos sensibles al repositorio.
- No revisar cambios documentales con la audiencia adecuada.
- No automatizar publicación cuando el proceso es repetitivo.
- No incluir documentación en la definición de terminado.
30.17 Qué debes recordar de este tema
- La documentación que cambia con el software debe tener control de versiones.
- Guardar documentación cerca del código facilita actualización conjunta.
- Las ramas y revisiones también sirven para documentación.
- La documentación por versión evita confusión en productos con varias versiones activas.
- Los mensajes de cambio ayudan a entender historial.
- No deben versionarse secretos ni datos sensibles reales.
- La definición de terminado debe incluir revisión documental cuando corresponda.
30.18 Conclusión
El control de versiones convierte la documentación en un artefacto técnico mantenible. Permite revisar, relacionar, publicar y recuperar cambios de forma ordenada, especialmente cuando la documentación evoluciona junto con el código.
En el próximo tema estudiaremos revisión, validación y pruebas de la documentación técnica.