Hay un momento en la carrera de casi todo desarrollador en el que te das cuenta de que el código ya no es el problema más difícil. El problema más difícil es explicarle a alguien de producto por qué el sistema funciona como funciona, o por qué un cambio que parece sencillo en realidad tiene diez implicaciones que no se ven a simple vista.
Durante mucho tiempo, mis herramientas para eso eran las mismas de siempre: una pizarra, una presentación armada de prisa, o en el mejor caso, un diagrama en draw.io que tardaba más en hacerse que en volverse obsoleto. El problema con esas herramientas no es que sean malas — es que viven desconectadas del código, del repositorio y de la realidad del sistema. En cuanto algo cambia, el diagrama miente.
Hasta que vi algo que cambió mi forma de trabajar.
La revelación: código que genera diagramas
Fue mi jefe quien me mostró por primera vez lo que Mermaid podía hacer. Había construido un script en Python que leía el esquema de la base de datos y generaba automáticamente un Entity Relationship Diagram en Mermaid. Ese diagrama vivía en el repositorio y se actualizaba solo con cada cambio mediante un flujo de GitHub Actions.
La primera vez que lo vi me quedé parado. No porque fuera magia — era código muy simple — sino porque conectaba dos mundos que yo siempre había tratado por separado: la documentación y el sistema real. Un diagrama que se genera desde la fuente de verdad no puede mentir. Es documentación viva.
Eso me abrió los ojos a algo más grande: si puedo generar un ERD automáticamente, ¿qué más puedo hacer con una herramienta que entiende texto y produce diagramas? ¿Qué pasa si la uso no solo para documentar para devs, sino para comunicar con producto?
El caso real: de 10 escenarios a 4 eventos
La respuesta llegó en un proyecto concreto. Estaba rediseñando un sistema de facturación para un equipo en otro país — lo cuento con más detalle en el post anterior sobre event-driven y facturación — y el punto de partida era una lista de más de 10 escenarios de negocio que el equipo de producto manejaba como casos independientes.
El equipo técnico los había modelado tal como producto los describía. El resultado era un sistema frágil, con lógica duplicada y casos borde que aparecían constantemente. Cuando empecé a analizar el dominio de verdad, encontré que todos esos escenarios eran variantes de solo 4 eventos de negocio reales.
El reto era convencer al equipo de producto de eso. No bastaba con decirlo — tenía que mostrarlo.
Usé dos tipos de diagramas Mermaid para hacerlo:
Timeline: para mostrar el patrón en el tiempo
El primer diagrama fue un timeline que mostraba cómo, a lo largo del ciclo de vida de una deuda, los 10+ escenarios que el equipo manejaba en realidad se repetían como instancias de los mismos 4 momentos. Ver los patrones distribuidos en el tiempo hizo inmediatamente visible algo que en texto era invisible: la complejidad era accidental, no esencial.
Sequence: para explicar cómo funcionarán los 4 eventos
El segundo diagrama fue un diagrama de secuencia que mostraba, de forma funcional y sin código, cómo cada uno de los 4 eventos fluiría a través del sistema: quién lo dispara, qué componentes se involucran, qué resultado produce.
sequenceDiagram
actor Usuario
participant Sistema
participant EventBridge
participant Facturacion as "Servicio de Facturación"
Usuario->>Sistema: Realiza pago parcial
Sistema->>Sistema: Valida monto y deuda
Sistema-->>Usuario: Confirma recepción del pago
Sistema->>EventBridge: Publica evento PagoParcialRegistrado
EventBridge->>Facturacion: Entrega evento PagoParcialRegistrado
Facturacion->>Facturacion: Actualiza saldo de la deuda
Facturacion->>Facturacion: Genera registros contables
Facturacion-->>EventBridge: Publica evento DeudaActualizada
EventBridge-->>Sistema: Notifica actualización de deuda
Sistema-->>Usuario: Muestra nuevo estado de la deuda
El equipo de producto entendió el modelo en esa misma reunión. No porque el diagrama fuera bonito — sino porque habló en su idioma: flujo, tiempo, actores, resultados. Sin terminología técnica innecesaria.
Los dos diagramas que más uso y cuándo
Después de ese proyecto, Mermaid se volvió una herramienta permanente en mi forma de trabajar. Estos son los dos tipos que más uso:
Sequence Diagram — mi favorito para comunicar con no técnicos
Es el diagrama que más valor me ha dado con áreas de negocio. Permite mostrar, a un nivel alto y sin código, cómo se comunican diferentes componentes entre sí: un proveedor externo con nuestros servicios, un usuario con el sistema, un evento disparando una cadena de reacciones.
Lo que hace especialmente útil al sequence es que funciona en dos niveles al mismo tiempo: para alguien de producto, muestra el flujo funcional de extremo a extremo. Para un desarrollador, es una guía de qué componentes debe tocar y en qué orden. Un solo diagrama, dos audiencias.
Flowchart — para flujos de proceso y decisiones
Cuando necesito mostrar un proceso con bifurcaciones, condiciones y caminos alternativos, el flowchart es la herramienta natural. Lo uso tanto para explicar procesos de negocio a producto como para documentar algoritmos y flujos de decisión para el equipo técnico.
flowchart TD
A[Evento recibido] --> B{Tipo de evento}
B -->|Adquisición| C[Procesar adquisición]
B -->|Pago parcial| D[Aplicar pago parcial]
B -->|Cierre de mes| E[Generar cierre de mes]
B -->|Liquidación| F[Calcular liquidación]
C --> G[Registrar en auditoría]
D --> G[Registrar en auditoría]
E --> G[Registrar en auditoría]
F --> G[Registrar en auditoría]
G --> H[Publicar eventos derivados]
Dónde viven los diagramas: la clave de la documentación viva
Una de las mayores ventajas de Mermaid es que no está atado a una sola herramienta. Dependiendo del contexto, uso:
- GitHub Wikis: el diagrama vive junto al código, se versiona con git, y cualquier developer del equipo puede actualizarlo en el mismo PR donde modifica el sistema.
- Confluence y Microsoft Loop: ambas tienen visualizadores nativos de Mermaid, útil cuando la documentación vive en herramientas corporativas.
- draw.io: tiene un generador que toma código Mermaid y produce el diagrama visual, práctico para presentaciones o documentos formales.
- Este mismo blog: integré un visor de Mermaid directamente, así que los diagramas que estás viendo en este post son código Mermaid renderizado en tiempo real. Hashnode también lo soporta de forma nativa. dev.to, por ahora, no tiene ese visor — ahí los bloques aparecen como código plano.
La versatilidad es real: el mismo bloque de texto produce el diagrama en la mayoría de esos contextos. No hay que rehacerlo, exportarlo ni mantener dos versiones.
Por qué Mermaid y no otra cosa
Es código, entonces es versionable. El diagrama vive en el repositorio, cambia con un commit, y su historial de cambios es el historial del sistema. Cuando alguien pregunta "¿cómo funcionaba esto hace seis meses?", el diagrama tiene la respuesta.
Es automatizable. Como el ERD que me mostró mi jefe: puedes generar diagramas desde una fuente de verdad y actualizarlos automáticamente con GitHub Actions o cualquier pipeline de CI. Documentación que se mantiene sola.
Es compatible con IA. Hoy en día, generar o modificar un diagrama Mermaid con un LLM es trivial. Describes el flujo en lenguaje natural y obtienes el código del diagrama. La barrera de entrada desapareció.
Cómo empezar mañana
Si nunca has usado Mermaid, abre mermaid.live y escribe tu primer diagrama de secuencia. La sintaxis es legible — en 15 minutos tienes algo funcional.
Si ya lo conoces pero no lo estás usando con negocio, el próximo proyecto donde tengas que explicar un flujo a alguien no técnico es tu oportunidad. Antes de armar la presentación, prueba hacer el sequence diagram primero. Te vas a sorprender de cuánto más rápido llega el entendimiento.
Y si quieres llevar la documentación al siguiente nivel, agrega un paso a tu pipeline de CI que genere o valide tus diagramas desde el código. El mismo principio del ERD automático aplica a cualquier artefacto del sistema que puedas describir en texto estructurado.
Mermaid no es solo una herramienta de diagramas. Es la forma en que los diagramas dejan de ser documentación que envejece y se convierten en parte viva del sistema.
¿Usas Mermaid en tu día a día? ¿Tienes algún caso de uso que no mencioné aquí? Me encantaría leerlo en los comentarios.
Top comments (0)