Mantener un modelo al día

La explicación habitual es la disciplina, y es falsa. Los mismos ingenieros que dejan un modelo a la deriva durante dos años mantienen su suite de pruebas en verde todos los días, y la diferencia no está en cuánto les importa: está en que una prueba en rojo detiene el pipeline y un diagrama equivocado no detiene nada.

El código está rodeado de maquinaria que obliga a fijarse en él justo cuando cambia: un compilador, una ejecución de pruebas, alguien que tiene que aprobar el cambio. Un modelo en un wiki no tiene nada de eso. Nada en el camino del ticket a producción obliga a nadie a abrir la página, así que nada saca nunca a la luz la discrepancia. El modelo no empeora: el sistema se mueve y el modelo se queda exactamente donde estaba.

Todo montaje que funciona tiene la misma forma: el modelo se coloca donde un paso ya existente va a tropezar con él.

Pon la vista en el repositorio. Un diagrama versionado como Mermaid junto al código aparece en el diff en cuanto se toca su archivo, y lo lee quien revisa el cambio. Es el único mecanismo de esta lista cuyo mantenimiento no cuesta nada, porque la revisión ya estaba ocurriendo.

Referencia las vistas desde los registros de decisión. Un registro breve de decisión de arquitectura que enlace la vista con la estructura que decidió hace que esa vista se abra cada vez que alguien pregunta por qué la estructura es así, que es justamente cuando importaría que estuviera equivocada.

Haz del modelo la fuente de algo que la gente necesita. Si la vista de despliegue genera el diagrama del runbook, o el modelo de dominio genera el glosario que consulta el equipo de soporte, entonces alguien lo nota en días y no en trimestres.

La otra mitad de la respuesta es que la mayoría de los modelos son demasiado grandes para mantenerlos, y eso no lo arregla ningún proceso. Si mantener el modelo costara un día al mes y el equipo tiene una hora, el modelo caducará por muy bien organizada que esté la revisión, así que lo honesto es recortarlo hasta esa hora.

Es la misma prueba que en el alcance, aplicada más tarde: las vistas que no pueden nombrar una decisión son las que se descartan, y descartarlas no es una pérdida porque nadie las leía. Lo que queda es lo bastante pequeño como para que se note cuando está mal.

Y luego borra el resto de verdad. Este es el paso que la gente no da, y el que tiene la aritmética más clara. Un diagrama que falta le cuesta al lector diez minutos de preguntar; uno equivocado con seguridad le cuesta un día y, con mala suerte, una decisión tomada sobre él. La documentación que no vas a mantener no es neutral: es una trampa con el logotipo de tu equipo.