Comment dessiner des diagrammes d’architecture logicielle (2022)

 (terrastruct.com)
3 points par GN⁺ 2023-10-28 | 1 commentaires | Partager sur WhatsApp
  • Un bon diagramme d’architecture permet de faire passer les idées et de maintenir la collaboration dans la durée grâce au bon niveau d’abstraction, à sa fraîcheur et à l’élimination des ambiguïtés, plutôt qu’à la décoration
  • Le principe de base est de minimiser la distance entre voisins en plaçant près les uns des autres les éléments connectés ; plus le diagramme grandit, plus il faut itérer en effaçant et en redessinant
  • La symétrie ne donne pas seulement une impression agréable : elle renforce aussi le sens, par exemple en plaçant les entrées et les sorties de côtés différents
  • Maintenir les formes alignées au centre rend même les concepts complexes moins compliqués visuellement et évite de désorganiser toute la disposition lors de l’ajout de nouveaux éléments
  • Les groupes de conteneurs étiquetés montrent d’un coup d’œil des séparations d’environnements comme AWS et Azure, des abstractions comme les implémentations de ReaderWriter, ou des ensembles d’objets liés comme Cores

Les conditions d’un diagramme durable

  • Un bon diagramme ne disparaît pas une fois la réunion terminée : il peut continuer à servir de point de référence pour les discussions et questions ultérieures
  • Les diagrammes qui durent ont quelques caractéristiques communes
    • Les éléments doivent être au bon niveau d’abstraction
    • Ils doivent rester à jour
    • Ils doivent être dépourvus d’ambiguïté
  • Les mêmes entités et relations peuvent être dessinées de plusieurs façons, mais certaines dispositions facilitent la collaboration pendant toute la durée du projet, tandis que d’autres disparaissent à la fin de la réunion
  • La beauté dont il est question ici n’est pas une décoration comme des ombres ou des coins arrondis, mais une beauté fonctionnelle qui transmet efficacement la pensée

Principes pour créer une disposition lisible

  • Minimiser la distance entre voisins

    • Le principe de base est de dessiner proches les uns des autres les nœuds connectés entre eux
    • C’est facile dans un petit diagramme, mais à mesure que le diagramme grandit et que de nouvelles connexions sont ajoutées, cette propriété se dégrade facilement
    • De même que l’on corrige les parties concernées lorsqu’on découvre un cas limite dans le code, ou que l’on modifie une phrase lorsqu’on repère un élément manquant dans un document, il faut aussi effacer et redessiner un diagramme destiné à la documentation lorsque c’est nécessaire
    • Dans un entretien, le coût de redessiner peut sembler lourd, mais pour un document utilisé par plusieurs personnes ou plusieurs équipes, les corrections itératives conduisent à un meilleur diagramme

  • Chercher la symétrie

    • La symétrie contribue fortement à l’impression esthétique d’un diagramme, et le cerveau humain a tendance à préférer la symétrie visuelle, comme dans les visages
    • Même si tous les nœuds sont aussi proches que possible de leurs voisins, un manque de symétrie peut donner l’impression d’un dessin légèrement de travers
    • Même si la distance d’un nœud à ses voisins augmente un peu, une version plus symétrique peut être plus agréable à regarder
    • Placer les entrées d’un côté et les sorties de l’autre renforce à la fois la symétrie et le sens du diagramme

  • Alignement au centre

    • L’alignement est un facteur important pour donner à un diagramme un aspect net
    • Un diagramme net rend les concepts plus clairs, tandis qu’un diagramme désordonné les fait paraître plus complexes
    • Si l’on place dès le départ des formes au hasard sur une toile vide, la disposition qui suit risque elle aussi de rester aléatoire
    • Comme l’alignement n’a de sens qu’entre au moins deux formes, maintenir l’alignement à chaque ajout d’un nouvel élément rend naturellement le diagramme plus propre
    • L’alignement naît souvent de la symétrie, mais ce n’est pas toujours le cas

  • Utiliser des groupes de conteneurs

    • Diviser le diagramme en plusieurs zones étiquetées aide le lecteur à comprendre plus facilement la structure
    • Les conteneurs peuvent ajouter les informations suivantes à un diagramme
      • Ajouter du contexte, par exemple « ces services sont sur AWS, ceux-ci sont sur Azure »
      • Montrer une abstraction, par exemple « ce sont tous des implémentations de ReaderWriter »
      • Regrouper des objets liés, comme rassembler core 1, 2, 3, 4 dans un conteneur « Cores »

Points abordés dans la suite

  • La partie 2 poursuivra avec les sujets suivants
    • Tracer les chemins des arêtes
    • Taille et position des libellés
    • Couleurs
    • Icônes

À lire aussi

1 commentaires

 
GN⁺ 2023-10-28
Avis de Hacker News

  • J’aime beaucoup créer des diagrammes avec D2. C’est similaire à mermaid.js, mais avec davantage d’options de mise en forme, et je trouve personnellement la syntaxe meilleure
    J’ai aussi écrit un court billet à ce sujet : https://victorbjorklund.com/build-diagrams-as-code-with-d2-d...

    • J’ai le sentiment que les diagrammes ne devraient pas être jolis. Par exemple, les couleurs ne devraient pas relever d’un choix esthétique ou artistique, mais servir à transmettre du sens
      Je comprends qu’un diagramme logiciel laid ne soit pas agréable à regarder, mais le décorer, c’est un peu comme ajouter des courbes à un graphique linéaire. Visuellement, ça peut mieux rendre, mais cela nuit aux données que l’on cherche à transmettre
    • J’ai suivi l’exemple et c’était vraiment chouette, mais contrairement aux indications, le rendu se faisait de haut en bas et non de gauche à droite
      J’ai rendu le premier exemple x -> y en SVG, puis ouvert uniquement le SVG dans le navigateur ; j’ai cherché dans toute la documentation comment contrôler l’alignement de sortie, sans trouver
      Comme la documentation et le résultat réel divergeaient, j’ai arrêté de l’utiliser. En cherchant "d2lang connection left to right", je suis arrivé sur https://d2lang.com/tour/layouts/, mais cette page ne semble pas liée depuis la documentation d’ensemble ; l’ajouter aiderait probablement les visiteurs
    • https://flowchart.fun/ m’a beaucoup aidé à dessiner très rapidement des organigrammes pour comprendre des processus système. Ce que j’ai préféré, c’est son côté intuitif et la rapidité d’itération, et le CSS personnalisé pour le styling était aussi assez utile
      Pour les organigrammes, je pense que c’est l’un des outils de diagrammes textuels les plus simples et rapides que j’aie utilisés jusqu’ici
    • D2 dispose d’un très bon moteur de mise en page, tala, mais il faut une licence payante pour l’utiliser. Les deux autres moteurs ne sont pas aussi bons
    • J’aime mermaid et je l’utilise souvent, mais il va falloir que je regarde D2 aussi. Je considère les diagrammes déclaratifs comme un outil puissant pour capturer des idées sous une forme lisible et les versionner comme n’importe quel autre texte

  • Quand un système commence à changer, les jolis diagrammes deviennent très difficiles à maintenir. Imaginez ajouter une nouvelle boîte au milieu d’un diagramme déjà complexe : il peut falloir une heure pour tout réaligner
    Dans les années 2020, le temps des développeurs est probablement mieux employé à gérer les diagrammes comme du code : https://www.ilograph.com/blog/posts/its-time-to-drop-drag-an...

    • Je plaisante toujours en disant que 10 % de la création d’un diagramme consiste à faire le diagramme lui-même, et 90 % à aligner les flèches
      Mais en fait, je crois que ce n’est pas vraiment une blague
    • J’ai maintenu un modèle C4 destiné à être importé et affiché dans structurizr.com, et franchement ce n’était pas agréable. Le code seul ne donnait pas la compréhension intuitive ni la vue d’ensemble qu’apporte un diagramme, et il n’y avait pas non plus de prévisualisation locale rapide, donc il fallait envoyer le code sur le serveur
      Le pire, c’est qu’ajouter une nouvelle boîte obligeait généralement à réaligner toutes les flèches. Résultat : le diagramme n’était pas maintenu à jour en continu
      Pour les diagrammes de séquence, l’utilisation de plantML était plus satisfaisante. Le travail en lui-même était plus simple, si bien que la sortie de l’interpréteur était généralement exploitable sans intervention manuelle
    • L’article aborde aussi le fait que modifier des diagrammes prend beaucoup de temps. En pratique, c’est vraiment le cas, et ce serait bien de pouvoir suivre correctement un schéma standardisé et que l’outil propose des options de mise en forme automatique
    • Quand on déplace des éléments et qu’on les réaligne, il faut réapprendre tout le diagramme. Si frobnitz était toujours en haut à droite et qu’il se retrouve soudain au milieu à gauche parce que c’est mieux pour l’alignement, cela peut aider quelqu’un qui le découvre, mais pour quelqu’un qui le regarde depuis six mois, c’est comme si c’était un tout autre objet
      C’est comparable à une UI laide. Même si elle est laide, les utilisateurs y sont déjà habitués. Dès qu’on la « range », on casse leur modèle mental et on les oblige à réapprendre
    • La valeur de cet investissement en temps dépend de la portée et de la durée de vie du diagramme
      Parfois, il ne s’agit que de faire un croquis pour organiser ses idées, qui sera jeté 20 minutes plus tard
      Mais si c’est une référence pour l’onboarding ou pour expliquer un système à d’autres équipes, l’heure passée à produire quelque chose de plus compréhensible peut largement être amortie

  • Pour dessiner ce genre de choses, j’utilise yEd. Même si je mets les boîtes et les flèches n’importe comment, quelques clics dans le menu suffisent à tout organiser automatiquement
    Il faut toutefois accepter des compromis. Les boîtes dans les boîtes ne finissent pas toujours bien. Malgré tout, cela permet de documenter beaucoup plus vite, et après quelques essais on comprend ce qui fonctionne ou non ; pour moi, c’est un bon compromis

    • Je me demande si yEd peut être utilisé gratuitement. Le SDK yWorks sur lequel il repose semble coûter des montants à cinq chiffres même pour un seul développeur sur un seul site web. S’ils ont des clients depuis près de 20 ans, ça doit être un outil assez puissant
    • Je fais pareil. Aucune raison de tout dessiner à la main
      Il suffit d’extraire les relations en TGF, de les importer, puis d’appliquer une mise en page hiérarchique
      Le format from, to, relation suffit
    • Pour des raisons similaires, j’utilise OmniGraffle

  • Il y a ici de fortes similitudes avec les schémas électriques, les diagrammes de circuits et d’autres dessins d’ingénierie. Il n’existe pas une seule « bonne » manière de faire
    Comme pour le code, la capacité à choisir de bonnes abstractions et représentations fait la différence entre une idée compréhensible et un chaos regrettable. Ce n’est pas une question de beauté ou d’esthétique, mais un outil qui exige une réflexion et un effort actifs dans la conception

    • Il est parfois vraiment difficile de maintenir un niveau d’abstraction cohérent. Surtout dans les diagrammes d’infrastructure, il est dur de résister à l’envie d’ajouter des détails de différents niveaux
      J’aimerais disposer d’un outil permettant de zoomer facilement à l’intérieur d’un diagramme, comme dans une animation à zoom infini

  • https://VisualFlows.io v1.0 sortira bientôt
    J’ai pu créer en quelques minutes une carte « d’architecture » animée du SaaS de la société mère : https://app.visualsitemaps.com/user_flows/share/e64da8ed-2ef...
    Les principales fonctionnalités sont Smart Sections, Smart Edges, Smart Node Deletion, les modes sombre/clair, l’embed, le glisser-déposer d’images/SVG/GIF, les icônes AWS/Windows/Google, Markdown prévu pour la semaine prochaine, etc.
    Voir Smart Sections : https://support.visualsitemaps.com/en/articles/6477269-how-t...

    • Je me demande pourquoi on devrait utiliser ça plutôt que https://whimsical.com, plus mature et avec une esthétique similaire

  • J’ai vraiment aimé cet article. Quand je dessine des diagrammes d’architecture, que j’écris de la documentation ou du code, ou que je fais quelque chose au travail, j’essaie de prendre un moment pour le rendre « agréable à regarder »
    C’est difficile d’expliquer pourquoi, mais je sais que, quand je le regarde ensuite, je l’apprécie davantage
    Je me suis un peu inquiété que ce ne soit peut-être pas la meilleure façon d’utiliser mon temps, mais je n’ai jamais entendu quelqu’un me dire de ne pas le faire
    Ce qui rend cet article intéressant, c’est qu’il explique quelque chose que je faisais à l’instinct comme une méthode pratique pour rendre quelque chose plus beau

    • Je fais pareil. Pour moi, coder est une activité assez visuelle. Je ne peux guère l’expliquer autrement qu’en parlant de « flux ». Si le code n’a pas de flux, je ne le trouve pas satisfaisant
      Je suis déconcerté quand je vois des membres de l’équipe qui semblent ne pas avoir de sens visuel du code. Ils ne mettent pas de ligne vide entre la fin d’une fonction et la déclaration de la suivante, ou bien ils alternent dans les signatures de fonction entre un paramètre par ligne et plusieurs paramètres par ligne. À mes yeux, ça saute aux yeux, mais eux n’ont pas l’air de s’en soucier
    • Même si on ne le partage avec personne, le simple fait de réfléchir à l’ordre des blocs et des éléments sur une page pousse à penser à la structure plus large et aux dépendances. C’est extrêmement utile
    • J’ai le même sentiment quand je crée des diagrammes réseau avec Visio. Je passe en mode Steve Jobs et je deviens obsédé par les petits détails
      Parfois ça prend du temps, mais il y a quelque chose de gratifiant. Je sais que j’ai un certain talent artistique technique, et au lycée je voulais devenir dessinateur industriel
    • C’est pour ça que le balisage existe. Il nous évite les ornements improductifs. Bien sûr, ça ne s’applique pas au code
    • « La discussion tourne autour de ce diagramme. Les gens s’en approchent distraitement et le regardent. On répond aux questions en pointant le diagramme. À intervalles réguliers au cours de la journée, les chaises se tournent vers cet objet central, et les gens joignent les mains derrière la tête. »
      C’est exactement le but de la visualisation

  • D2 est bien pour ce genre d’usage. Dans mon précédent poste, j’avais écrit un programme qui analysait tous les fichiers serverless.yml et générait automatiquement un énorme diagramme D2
    Nous faisions des microservices sur AWS, et c’était appréciable que le diagramme se mette à jour automatiquement quand le système grossissait. Je l’avais conçu pour pouvoir le découper en petits diagrammes par sous-système, par exemple en les séparant par SNS topic

    • J’aime bien draw.io aussi

  • Je ne comprends pas le premier exemple. L’auteur parle d’un nœud non planifié, lui donne effectivement le nom « I was unplanned », puis dit « si on l’avait planifié à l’avance »
    Dans le contexte d’un diagramme, je ne vois pas comment on peut planifier à l’avance quelque chose de non planifié. Je me demande s’il veut dire qu’il faut laisser suffisamment d’espace autour de tous les nœuds
    De plus, l’amélioration proposée donne l’impression que « something » et « I was unplanned » utilisent le même canal ou mécanisme lorsqu’ils interagissent avec « engine »

  • J’utilise Miro, et pour du contenu de haut niveau ou de l’idéation, l’outil de post-its est plutôt correct. En revanche, il ne va pas au-delà d’un niveau intermédiaire
    Une fois les composants et les systèmes définis, il existe des outils mieux adaptés à ce travail

  • Si la documentation du projet est en Markdown, on peut insérer des diagrammes avec des blocs ```plantuml au lieu d’utiliser un binaire séparé
    Dans GitLab, le rendu est joli quand on consulte les fichiers .md dans le navigateur. GitHub n’a pas encore cette fonctionnalité