Por qué la documentación siempre está desactualizada
La documentación de arquitectura suele nacer bien: alguien dedica una semana a escribirla y dibujar los diagramas. Muere poco después, por una razón simple: vive en un sitio distinto al sistema. Cada cambio en el sistema exige acordarse de cambiar también el documento, y nadie se acuerda.
El problema no es de disciplina. Es de diseño: si mantener la documentación es un trabajo aparte, no se hará.
Documentación como código
La alternativa es tratar la documentación igual que el código:
- Vive en el mismo repositorio que el sistema y se revisa en los mismos cambios.
- Tiene una fuente única: el texto en un formato simple y los diagramas descritos como datos, no dibujados a mano.
- Las salidas se generan: documento, diagramas, página web y versión imprimible salen de esa fuente con una plantilla común. Nunca se editan a mano.
- Un estándar visual compartido: mismos colores, iconos y estructura en todos los documentos de la organización, para que se lean igual.
Qué incluir y qué no
Una documentación de arquitectura útil es corta y estable:
- Visión general y zonas.
- Componentes y para qué sirve cada uno.
- Flujos principales, numerados.
- Requisitos de calidad acordados.
- Registros de decisión.
- Cómo se despliega y cómo se recupera.
Lo que cambia cada semana (versiones exactas, direcciones, recuentos) no se escribe a mano: se obtiene del propio sistema o se enlaza.
La prueba de que funciona
Una documentación de arquitectura está viva si alguien que llega nuevo puede entender el sistema en una tarde y si un cambio de arquitectura no se da por terminado hasta que la documentación lo refleja. Lo segundo solo es posible si actualizarla es tan fácil como cambiar una línea en el mismo repositorio.
Cómo lo aplicamos: Arquitectura Cloud.