Diagramas como código con Mermaid

Creo que a estas alturas sería muy innecesario hablar del formato de documentación Markdown. Es el formato por defecto para la elaboración de documentos y cuenta con una incontable cantidad de ventajas por permitir tratar a un documento de la misma manera que puedes tratar a un archivo de código.

Entre sus ventajas están:

• La edición de múltiples partes del documento sin problema.
• Puedes establecer versiones del mismo y en caso de necesitar algo más lo puedes traer de vuelta de versiones anteriores.
• Puedes tener mucho mejor control sobre el documento que manejarlo con aplicaciones como Word.

Ahora, despues de pasar por los documentos podemos hablar de los diagramas por incluir. Hasta hace muy poco lo que hacía era crear un diagrama de flujo en Power Point, crear una imagen y agregarla en mi archivo markdown.

Pero todo cambió con Mermaid.

¿Qué es Mermaid?

Mermaid es una sintaxis similar a Markdown donde puedes usar texto para describir y automaticamente generar diagramas. Puedes generar diagramas de flujo, diagramas UML, gráficas de pie, diagramas gantt y más.

Ahora veo mucho más preferible crear un diagrama de este modo para evitar usar más herramientas de manera innecesaria y desde el mismo VS Code sin mayor problema y con la posibilidad de una edición controlada por versiones.

¿Qué puedo hacer con Mermaid?

Puedes crear diagramas de tipo:

• Flowchart
• Gantt
• StateDiagram
• Gitgraph
• Pie
• SequenceDiagram
• ClassDiagram

Y como conectores, podrás crear enlaces por medio de flechas y conectores de flechas, algo así como los signos de mayor qué y menor qué. No creo que sea muy necesario adentrarnos mucho en la sintaxis, es tan sencilla que lo más fácil es ver un ejemplo simple de cada uno de los diagramas.

Flowchart

El diagrama de flujo por excelencia.

Código:

graph TD
   A(Sugiere una nueva funcionalidad) --> B{El equipo la evalúa}
   B -->|No| H(Idea rechazada)
   B -->|Si| C(Entra a backlog) --> D{Puede ir en el <br>siguiente sprint}
   D -->|No| E(Evalúa en qué sprint puede ir) 
   D -->|Si| F(Asigna tareas)

Resultado:

Gantt

Dime que no pasaste por la asignación de tiempos por medio de un diagrama de Gantt y te diré lo joven que eres.

Código:

gantt
 title Calendario de actividades
    dateFormat  YYYY-MM-DD
    section Fase 1
    Investigación y requerimientos :done, a1, 2020-03-08, 2020-03-10
    Revisión y documentación : after a1, 5d
    section Fase 2
    Implementacion : active, a2, 2020-03-15, 3d
    Testing      :after a2, 3d

Resultado:

StateDiagram

Muy parecido al diagrama de flujo pero más adaptado para representar el comportamiento de un sistema.

Código:

stateDiagram-v2
    [*] --> Backlog
    Backlog --> UserStory
    UserStory --> Tasks
    Tasks --> Nueva
    Tasks --> Activa
    Tasks --> Resuelta
    Tasks --> Cerrada
    Nueva --> [*]
    Activa --> [*]
    Resuelta --> [*]
    Cerrada --> [*]

Resultado:

GitGraph

Mi favorito, me ha ahorrado muchísimo tiempo al hablar de unificación de ramas y muchas cosas más.

Código:

gitGraph:
options
{
    "nodeSpacing": 150,
    "nodeRadius": 10
}
end
commit
branch newbranch
checkout newbranch
commit
commit
checkout master
commit
commit
merge newbranch

Resultado:

Pie

¡Al fin! Una manera más práctica de crear un gráfico que en Excel.

Código:

pie title Commits en GitHub
	"Sábado" : 4
	"Lunes" : 5
	"Martes" : 7
        "Miércoles" : 3
        "Jueves" : 2

Resultado:

SequenceDiagram

Creo que de todos los diagramas es el que más uso veo que le han dado. Es muy práctico para mostrar procesos

Código:

sequenceDiagram
    Miranda->>+Amin: Hola papá ¿Cómo estás?
    Miranda->>+Amin: ¿Puedes escucharme papá?
    Amin-->>-Miranda: Hola hija. ¡Puedo escucharte!
    Amin-->>-Miranda: ¡Me siento muy bien!
    Marce ->> Miranda: ¡Hola hija! También puedo escucharte.
    Miranda ->> Marce: ¡Eso me da mucho gusto mamá!

Resultado:

ClassDiagram

Mi segundo favorito, la mejor herramienta para representar clases y propiedades.

Código:

classDiagram
    Animal <|-- Perro
    Animal <|-- Pez
    Animal <|-- Cebra
    Animal : +int age
    Animal : +string gender
    Animal: +isMammal()
    Animal: +mate()
    class Perro{
      +string beakColor
      +swim()
      +quack()
    }
    class Pez{
      -int sizeInFeet
      -canEat()
    }
    class Cebra{
      +bool is_wild
      +run()
    }

Resultado:

Conclusión

Con este tipo de diagramas salvarás mucho tiempo además de que podrás incorporarlo como texto plano a tus documentos evitando así subir binarios y además podrás someterlos a ediciones constantes sin mayor problema. ¡Una herramienta que no puede faltar en tu arsenal!

Puedes ver su repositorio aquí y probar el editor en línea aquí.