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í.