Diagram as code resuelve el formato del archivo, no el mantenimiento. Un diagrama textual también puede quedar obsoleto o ser imposible de revisar. El flujo debe definir por qué existe, quién lo mantiene y qué cambios exigen actualizarlo.
Asigna a cada diagrama una decisión
Escribe su propósito junto al código. “Muestra los límites de confianza de la API pública” se puede comprobar; “Arquitectura del sistema” es demasiado amplio. Usa un diagrama de flujo para decisiones, uno de secuencia para el orden, ER para relaciones de datos y Gantt para calendarios ligeros.
Guarda el código junto a la documentación relevante
Si explica una API, colócalo cerca de su documentación. Esa proximidad favorece propiedad y revisión. Exporta una imagen solo cuando la plataforma no renderice Mermaid. Si se versionan código y SVG, identifica cuál es la fuente de verdad y no edites manualmente el archivo generado.
Define desencadenantes de actualización
Una lista útil incluye cambios como:
- Añadir o eliminar un servicio, o cambiar su propietario.
- Modificar un límite de confianza o destino de datos.
- Convertir una llamada en asíncrona o añadir una rama de error.
- Cambiar opcionalidad o cardinalidad en la base de datos.
- Cambiar un hito de entrega documentado.
Revisa el significado antes que el aspecto
Verifica primero nodos, relaciones, orden y etiquetas. El diseño y el color vienen después. Mantén cambios pequeños, ID estables y una sentencia por línea. Separa un reformateo masivo del cambio semántico.
Valida el entorno de publicación
Las versiones Mermaid y las políticas de seguridad varían. Prueba la sintaxis en el renderizador final y evita HTML o enlaces interactivos si debe funcionar con políticas estrictas.
Usa el editor Mermaid para iterar y exportar, pero conserva el código versionado y su revisión como flujo duradero.