Mermaid fez os diagramas como código pegarem: diagramas de sequência viraram texto dentro do Markdown

O UML foi a grande tentativa do software de padronizar diagramas de projeto: a OMG o aceitou em 1997 e a ISO o adotou em 2005. Ele entrou em colapso sob o próprio peso — a documentação do UML 2.2 passava de 1.000 páginas e o padrão ficou atrelado a ferramentas CASE pesadas e a um trabalho prévio oneroso, de modo que, nos anos 2020, defensores e detratores concordavam que ele estava essencialmente morto.

Um artefato sobreviveu a ele: o diagrama de sequência, um mapa simples de mensagens que fluem entre componentes. Quem o utilizava conseguia desenhá-lo, mas as ferramentas tornavam isso penoso — jessems, desenvolvedor na BitHawk, achava lento e frágil arrastar formas no Lucidchart, com qualquer mudança futura arruinando o layout.

A saída foi o Mermaid, uma biblioteca JavaScript em que se declara o diagrama como texto simples: participantes, setas e mensagens escritos dentro de um bloco de código Markdown, renderizados pela cadeia de ferramentas do Markdown. O autor experimentou esperando que código-sobre-código parecesse errado, mas achou rápido, indolor e bonito; passou a embutir diagramas de sequência nos planos de implementação de suas histórias de usuário, pré-visualizando-os com hot reload e exportando-os como imagens para colar em campos HTML.

O motivo de ter pegado é que o diagrama se tornou um artefato de código comum. Ele fica ao lado da história que documenta, aparece em diff na revisão de código, é atualizado com uma edição de uma linha em vez de um redesenho, e é renderizado em qualquer lugar onde o Markdown é renderizado — o Markdown do GitHub suporta Mermaid nativamente, apontaram comentaristas na thread do Hacker News. O fundador do Mermaid enquadrou isso como uma simplicidade informal substituindo a complexidade rígida das ferramentas da era do Rational Rose.

Transformar o diagrama em um artefato de código: digitá-lo como texto no Markdown e deixar o renderizador desenhá-lo

Digitar um diagrama é mais rápido do que arrastá-lo, então o custo de autoria cai de uma sessão no canvas para algumas linhas ao lado do documento.

Texto versiona e compara por diff como código, então atualizar um diagrama é uma edição de uma linha na revisão em vez de um redesenho frágil.

Renderizadores de Markdown já existem em toda parte, então o diagrama aparece onde a equipe já lê e comenta documentos.

O UML morreu por acumular complexidade; o Mermaid manteve apenas o artefato útil e removeu o custo de ferramentas em torno dele.

Um padrão sobrevive ao cortar custo onde as pessoas já trabalham: o diagrama que vence é aquele que você consegue digitar em um documento e comparar por diff na revisão.

O post alcançou 207 pontos e 111 comentários no Hacker News em 24 de julho de 2023. Comentaristas observaram que o Markdown do GitHub renderiza Mermaid nativamente, compararam-no com PlantUML, d2 e Graphviz, e recomendaram ecossistemas Markdown como o Docusaurus, que o renderiza com um único comando de instalação. O autor manteve o fluxo de trabalho na BitHawk, redigindo planos de implementação cujos diagramas de sequência vivem dentro de arquivos Markdown, com o mermaid-cli exportando-os como imagens quando os registros exigiam HTML.