Visualiseren zonder te Tekenen: Automatiseer je diagrammen met Mermaid.js
Versiebeheer op je diagrammen is eindelijk mogelijk.
Wat is Diagrams-as-Code?
Diagrams-as-Code is een aanpak waarbij je diagrammen niet tekent met een visuele tool, maar schrijft als tekstuele code. Net zoals developers applicaties bouwen met code, beschrijf je als analist je procesflows, sequence diagrammen en architectuurplaten in een eenvoudige tekstnotatie.
De voordelen zijn direct duidelijk: je diagrammen zijn versiebeheerbaar in Git, reproduceerbaar op elke machine, en je hebt geen dure licenties nodig. Mermaid.js is de meest populaire open-source oplossing voor deze aanpak en wordt inmiddels native ondersteund door GitHub, GitLab, Notion en vele andere platformen.
Flowcharts: het werkpaard
De flowchart is het meest gebruikte diagramtype voor business analisten. In Mermaid beschrijf je een flowchart met eenvoudige tekstuele syntaxis. Nodes zijn woorden tussen haakjes, pijlen verbinden ze, en je kunt labels toevoegen aan elke verbinding.
Mermaid-code
flowchart TD
A[Klant dient aanvraag in] --> B{Compleet?}
B -->|Ja| C[Beoordeel aanvraag]
B -->|Nee| D[Vraag aanvulling]
D --> A
C --> E{Goedgekeurd?}
E -->|Ja| F[Verstuur bevestiging]
E -->|Nee| G[Verstuur afwijzing]
F --> H[Archiveer dossier]
G --> HDit is alles wat je nodig hebt. Geen muis, geen slepen, geen uitlijnen. De code beschrijft de logica en Mermaid genereert automatisch een netjes uitgelijnde flowchart. Wijzigingen zijn een kwestie van tekst aanpassen — en die wijzigingen zijn traceerbaar in je versiebeheer.
Sequence Diagrammen: interacties in beeld
Sequence diagrammen zijn onmisbaar voor het documenteren van systeemintegraties en API-interacties. Ze tonen wie wat communiceert met wie, in welke volgorde. In Mermaid beschrijf je dit als een script van berichten tussen actoren.
Mermaid-code
sequenceDiagram
actor Klant
participant WebApp
participant API
participant Database
Klant->>WebApp: Vult formulier in
WebApp->>API: POST /aanvraag
API->>Database: INSERT aanvraag
Database-->>API: OK (id: 12345)
API-->>WebApp: 201 Created
WebApp-->>Klant: Bevestigingspagina
Note over API,Database: Async verwerking start
API->>API: Valideer bedrijfsregels
API-->>Klant: E-mail notificatieHet sequence diagram maakt in één oogopslag duidelijk welke systemen betrokken zijn, welke berichten worden uitgewisseld, en waar asynchrone processen plaatsvinden. Ideaal voor het afstemmen van integratie-ontwerpen met development teams.
Gantt Charts: planning in code
Zelfs eenvoudige projectplanningen kun je met Mermaid vastleggen. Handig als je een sprint-planning of release-roadmap wilt documenteren zonder een apart planningtool te openen.
Mermaid-code
gantt
title Release Planning Q2 2026
dateFormat YYYY-MM-DD
section Analyse
Requirements verzamelen :a1, 2026-04-01, 10d
Procesmodellering :a2, after a1, 5d
Stakeholder-review :a3, after a2, 3d
section Development
Sprint 1 - Core features :d1, after a3, 14d
Sprint 2 - Integraties :d2, after d1, 14d
section Testing
UAT :t1, after d2, 7d
Bugfixes :t2, after t1, 5d
section Release
Go-live voorbereiding :r1, after t2, 3d
Go-live :milestone, after r1, 0dGantt charts in Mermaid zijn niet bedoeld als vervanging voor MS Project of Jira-roadmaps. Ze zijn perfect voor het snel vastleggen van een planning in documentatie, een README of een Confluence-pagina — zonder dat je een apart bestand hoeft te beheren.
Meer diagramtypen
Mermaid ondersteunt nog veel meer diagramtypen die relevant zijn voor business analisten. Hier een overzicht van de meest bruikbare:
State Diagram
Modelleert de levenscyclus van een entiteit. Ideaal voor order-statussen, aanvraagprocessen of documentworkflows.
Entity Relationship
Beschrijft relaties tussen data-entiteiten. Handig voor het documenteren van domeinmodellen en database-ontwerpen.
Class Diagram
UML-klassendiagrammen voor objectmodellen. Nuttig als je met developers communiceert over domeinobjecten.
Pie Chart
Eenvoudige taartdiagrammen voor het visualiseren van verdelingen in documentatie en presentaties.
Mindmap
Hiërarchische mindmaps voor het structureren van ideeën, features of requirements in een boomstructuur.
User Journey
User journey maps met taken en tevredenheidsscores. Perfect voor het documenteren van klantreizen.
Integraties: waar draait Mermaid?
Een van de grootste voordelen van Mermaid is de brede ondersteuning in platformen die je waarschijnlijk al gebruikt. Je hoeft geen apart programma te installeren.
Mermaid wordt native gerenderd in README-bestanden, issues, pull requests en wiki-pagina's. Gewoon een Mermaid-codeblok toevoegen en GitHub toont het diagram.
Gebruik een code-blok met de taal 'mermaid' en Notion rendert het diagram automatisch. Ideaal voor interne kennisbanken en projectdocumentatie.
Via de Mermaid for Confluence plugin kun je diagrammen direct in Confluence-pagina's embedden. De diagrammen worden live gerenderd.
De Mermaid Preview-extensie toont een live preview van je diagram terwijl je typt. Autocomplete en syntax highlighting inbegrepen.
Net als GitHub ondersteunt GitLab native Mermaid-rendering in Markdown-bestanden, issues en merge requests.
Voordelen van Diagrams-as-Code
Waarom zou je overstappen van een visuele tool naar code? De voordelen zijn fundamenteel anders dan bij traditionele diagramtools:
- ●Versiebeheer: Je diagrammen leven in Git naast je code en documentatie. Elke wijziging is traceerbaar: wie heeft wat wanneer aangepast en waarom? Geen 'diagram_v3_final_FINAL.pptx' meer.
- ●Reproduceerbaarheid: Een diagram in code ziet er overal hetzelfde uit. Geen problemen met fonts, kleuren of uitlijning op andere machines. De code is de single source of truth.
- ●Geen licentiekosten: Mermaid is volledig open source en gratis. Geen per-seat licenties, geen enterprise-contracten, geen vendor lock-in. De code is van jou.
- ●Snelheid: Een ervaren Mermaid-gebruiker maakt een diagram in een fractie van de tijd die het kost in een visuele tool. Geen muis nodig, geen uitlijnen, geen opmaak.
- ●Doorzoekbaarheid: Omdat diagrammen tekst zijn, kun je ze doorzoeken met grep, zoeken in je IDE, en opnemen in full-text search indexen. Probeer dat maar eens met een Visio-bestand.
- ●Automatisering: Genereer diagrammen automatisch vanuit data. Een script kan een database-schema omzetten in een ER-diagram, of een API-specificatie in een sequence diagram.
Wanneer Mermaid wél en niet de juiste keuze is
| Situatie | Mermaid? |
|---|---|
| Technische documentatie in Git | Ja, ideaal |
| Snelle sketch tijdens een meeting | Ja, als je de syntax kent |
| Complexe BPMN met 20+ activiteiten | Nee, gebruik Lucidchart |
| Interactieve workshop met stakeholders | Nee, gebruik Miro |
| API-integratie documenteren | Ja, sequence diagrams |
| Presentatie voor management | Nee, gebruik een gepolijste tool |
Onthoud
Mermaid vervangt je visuele diagramtools niet volledig, maar vult ze aan op een fundamentele manier. Voor technische documentatie, developer-communicatie en alles wat in versiebeheer moet leven, is Diagrams-as-Code de toekomst. Begin met flowcharts en sequence diagrammen — dat dekt 80% van je dagelijkse diagrambehoeften.
Reacties (3)
Erg nuttig artikel! Ik heb de methode direct toegepast in mijn huidige project en het helpt enorm bij het structureren van mijn aanpak.
Goed geschreven en praktisch. Zou wel meer voorbeelden willen zien van toepassing in een overheidsomgeving.
Dit sluit mooi aan bij wat we in ons Scrum-team doen. Ga dit zeker delen met mijn collega's.
Plaats een reactie
Reacties worden gemodereerd voordat ze zichtbaar worden.