UML en un repositorio: Mermaid

Mermaid es el que menos modelo transporta de los tres formatos de exportación y el único que resuelve el problema que la mayoría de la documentación tiene de verdad. XMI lleva el metamodelo; .qea lleva el metamodelo y la disposición; Mermaid lleva aproximadamente lo que cabe en un párrafo de texto, y se renderiza en un README sin ningún paso de build.

Ese es todo el argumento, y es bueno. Un diagrama exportado como PNG a un wiki está mal en un trimestre y nadie se da cuenta, porque nada en un cambio de código obliga a nadie a mirarlo. Un diagrama en docs/architecture.md aparece en un diff cuando se toca su archivo, y quien sabe leer el cambio ve al diagrama contradecirlo.

Incluso en las filas buenas conviene nombrar lo que se pierde: estereotipos, notas, restricciones y todo rastro de disposición. Mermaid dispone sus propios diagramas, así que la colocación en la que invertiste una hora no sobrevive, y para un diagrama que se regenerará en cada cambio eso es una ventaja más que una pérdida.

Exporta las vistas que un desarrollador abriría de verdad, que casi nunca son todas. Un diagrama de clases del núcleo del dominio y un diagrama de secuencia del flujo que todos depuran son mejor repositorio que catorce archivos que nadie lee.

Versiona el Mermaid, no una imagen renderizada. GitHub, GitLab y la mayoría de generadores de sitios estáticos renderizan bloques mermaid directamente. Una imagen guardada junto al origen es una segunda copia que acabará contradiciéndolo.

Regenera en vez de editar a mano. En cuanto alguien corrige un nombre de clase en el Markdown en lugar de en el modelo, la exportación ha dejado de ser una exportación y las dos versiones empiezan a separarse: exactamente el fallo del que trata mantener un modelo al día.