Diagrammi scritti come testo: Mermaid e PlantUML

Un diagramma disegnato con un programma grafico ha un problema che emerge con il tempo: modificarlo è scomodo. Bisogna ritrovare il file sorgente, ricordare con quale programma era stato fatto, spostare riquadri e frecce a mano. Così, quando il processo cambia, il diagramma resta com'era e smette di essere vero.

I diagrammi scritti come testo ribaltano l'approccio. Si descrive in poche righe che cosa è collegato a cosa, e uno strumento disegna il diagramma in automatico. Il sorgente sta accanto al documento, si modifica con un editor qualsiasi e si versiona con Git come il resto.

Mermaid

Mermaid è lo strumento più diffuso per i diagrammi testuali dentro Markdown. Molte piattaforme Git, wiki e app di note lo visualizzano direttamente: basta un blocco di codice marcato come mermaid.

Diagramma di flusso

```mermaid
flowchart TD
    A[Richiesta ricevuta] --> B{Documento completo?}
    B -- Sì --> C[Protocollare]
    B -- No --> D[Chiedere integrazione]
    D --> A
    C --> E[Archiviare]
```

• flowchart TD indica un diagramma dall'alto verso il basso; LR lo dispone da sinistra a destra.
• Le parentesi quadre creano un riquadro, le graffe un rombo di decisione, le tonde un riquadro arrotondato.
• --> è una freccia; -- testo --> aggiunge un'etichetta.

Diagramma di sequenza

È utile per descrivere chi comunica con chi e in che ordine, per esempio in una procedura di accesso:

```mermaid
sequenceDiagram
    Utente->>Portale: inserisce credenziali
    Portale->>Server: verifica
    Server-->>Portale: richiede secondo fattore
    Portale-->>Utente: chiede il codice
    Utente->>Portale: invia il codice
    Portale-->>Utente: accesso consentito
```

Le frecce piene indicano una richiesta, quelle tratteggiate una risposta.

Altri tipi

Mermaid supporta anche diagrammi di Gantt per pianificazioni semplici, diagrammi di stato, diagrammi entità-relazione per descrivere tabelle di un database, diagrammi delle classi e linee temporali.

PlantUML

PlantUML è più vecchio e più completo, soprattutto per i diagrammi UML usati nello sviluppo software. Il testo è racchiuso tra @startuml ed @enduml:

@startuml
actor Operatore
participant "Sistema di backup" as B
database Archivio

Operatore -> B : avvia copia
B -> Archivio : scrive i dati
Archivio --> B : conferma
B --> Operatore : rapporto finale
@enduml

Richiede Java per funzionare in locale, e per alcuni tipi di diagramma anche Graphviz. Molti editor hanno estensioni che mostrano l'anteprima mentre si scrive, e si può integrare in generatori di documentazione come Sphinx o nei programmi di wiki aziendali.

Quale scegliere

Per documentazione, procedure e README, Mermaid è quasi sempre sufficiente. PlantUML conviene quando servono diagrammi UML rigorosi o tipi particolari.

Vantaggi concreti

• Modifiche rapide: aggiungere un passaggio significa scrivere una riga, e la disposizione si ricalcola da sola.
• Storia delle versioni: Git mostra esattamente che cosa è cambiato in un diagramma, cosa impossibile con un'immagine.
• Coerenza: tutti i diagrammi di un progetto hanno lo stesso aspetto.
• Revisione: chi rivede legge il testo del diagramma come qualsiasi altra modifica.

Limiti da conoscere

• La disposizione è automatica: non si controlla al millimetro dove finiscono i riquadri. Per schemi molto curati, come una mappa di rete da appendere al muro, un programma grafico come draw.io resta più adatto.
• I diagrammi grandi diventano confusi: oltre venti o trenta elementi, meglio dividere in più diagrammi.
• La visualizzazione dipende dalla piattaforma: un blocco Mermaid che appare come diagramma in un repository può apparire come testo in un altro programma. Se il documento deve essere esportato, conviene generare un'immagine SVG o PNG.
• Accessibilità: il diagramma va accompagnato da una breve descrizione testuale di ciò che mostra.

Nel mio lavoro uso Mermaid per descrivere flussi di procedure e passaggi tra sistemi direttamente nella documentazione: il diagramma viene aggiornato nella stessa modifica che cambia il processo.

In sintesi

• I diagrammi testuali si scrivono in poche righe e vengono disegnati in automatico.
• Mermaid è integrato in molte piattaforme Markdown ed è il più semplice da adottare.
• PlantUML offre più tipi di diagramma e più controllo, ma richiede Java.
• Si versionano e si rivedono come testo, e restano aggiornati più facilmente.
• Per schemi molto curati o molto grandi, un programma grafico o più diagrammi piccoli sono preferibili.