UML dans un dépôt : Mermaid

Mermaid est celui des trois formats d'export qui porte le moins de modèle, et le seul qui règle le problème que la plupart des documentations ont réellement. XMI porte le métamodèle ; .qea porte le métamodèle et la mise en page ; Mermaid porte à peu près ce qui tient dans un paragraphe de texte - et s'affiche dans un README sans aucune étape de build.

C'est tout l'argument, et il est bon. Un diagramme exporté en PNG dans un wiki est faux au bout d'un trimestre et personne ne le remarque, parce que rien dans une modification de code n'oblige quiconque à le regarder. Un diagramme dans docs/architecture.md apparaît dans un diff dès que son fichier est touché, et un relecteur capable de lire le changement voit le diagramme le contredire.

Même dans les bonnes lignes, il faut nommer ce qui se perd : les stéréotypes, les notes, les contraintes et toute trace de mise en page. Mermaid dispose ses diagrammes lui-même : l'agencement sur lequel vous avez passé une heure ne survit pas - et pour un diagramme régénéré à chaque changement, c'est un avantage plutôt qu'une perte.

Exportez les vues qu'un développeur ouvrirait réellement, ce qui n'est presque jamais toutes. Un diagramme de classes du cœur du domaine et un diagramme de séquence du flux que tout le monde débogue font un meilleur dépôt que quatorze fichiers que personne ne lit.

Versionnez le Mermaid, pas une image rendue. GitHub, GitLab et la plupart des générateurs de sites statiques affichent les blocs mermaid directement. Une image déposée à côté de la source est une seconde copie qui finira par la contredire.

Régénérez plutôt que de modifier à la main. Dès que quelqu'un corrige un nom de classe dans le Markdown au lieu du modèle, l'export a cessé d'être un export et les deux versions commencent à diverger - c'est exactement le mode d'échec dont traite garder un modèle à jour.