Documenter et communiquer l’architecture

Bienvenue dans le chapitre 4 : Documenter et communiquer l’architecture. Ce chapitre montre comment décrire une architecture logicielle pour que les bonnes personnes la comprennent, et pour que la description reste fidèle. Il est pratique de bout en bout, et il s’appuie sur une même plateforme de livraison de repas comme exemple fil rouge, pour que vous puissiez comparer chaque technique sur le même système.

Une architecture qui n’existe que dans la tête de quelques personnes est fragile. Personne en dehors de la salle ne peut la revoir, le prochain ingénieur qui arrive ne peut pas l’apprendre, un auditeur ne peut pas la vérifier, et elle part avec les personnes qui la détiennent. Il est facile de se tromper dans les deux sens avec la documentation. Les équipes qui écrivent trop peu perdent les raisons de leur structure, et refont sans cesse les mêmes débats. Les équipes qui écrivent trop produisent des wikis auxquels personne ne se fie. Le principe directeur du chapitre est donc simple : écrire pour le lecteur. Décidez qui utilisera chaque élément de documentation et ce dont il a besoin, écrivez cela de façon brève et exacte, et n’écrivez rien d’autre.

Le chapitre s’adresse aux développeurs, aux architectes et aux responsables techniques. Il s’appuie sur les chapitres 1 à 3 : les décisions et les structures qu’il faut maintenant décrire. Les sections un point cinq, sur les parties prenantes et les préoccupations, et un point six, sur les décisions et les compromis, sont des bases particulièrement utiles. Et il prépare le chapitre 5, qui ouvre le catalogue des styles architecturaux, décrits avec les outils que vous apprenez ici.

Le chapitre compte huit sections. La section quatre point un se demande à qui s’adresse la documentation, et comment décider de ce qui mérite d’être écrit. La réponse courte : écrivez à la main ce que le code ne peut pas vous dire, et générez ce que le code indique déjà. La section quatre point deux présente l’idée centrale selon laquelle un seul diagramme ne suffit jamais. Une architecture se décrit au moyen de plusieurs vues, chacune répondant aux préoccupations de parties prenantes précises. La section quatre point trois transforme cela en l’approche pratique la plus utilisée, le modèle C4 de Simon Brown, avec quatre niveaux de zoom et un petit ensemble de règles de notation qui rendent les diagrammes compréhensibles par eux-mêmes. La section quatre point quatre couvre les parties du langage de modélisation unifié, ou UML, que les architectes utilisent encore, comme les diagrammes de séquence et d’états-transitions, et explique quand leur précision vaut l’effort.

Ce diagramme de la section quatre point un vous aide à décider comment documenter n’importe quelle information. L’axe vertical demande si elle peut être retrouvée à partir du code. L’axe du bas demande à quelle fréquence elle change. En haut à gauche : ce que le code ne peut pas vous dire, et qui change rarement. Le contexte et la portée, les objectifs de qualité, et les décisions avec leurs raisons. Écrivez-les à la main, et conservez-les. En haut à droite : ce qui change plus souvent, comme les vues de conteneurs et de déploiement. Gardez-les à côté du code, et revoyez-les à chaque changement. En bas à droite : ce que le code indique déjà, et qui change souvent, comme les diagrammes de classes et les références d’API. Générez-les dans le pipeline. Ne les écrivez jamais à la main. Et en bas à gauche : ce qu’on peut lire dans le code et qui change rarement, comme la pile technologique ou les commandes de build. Un bref renvoi dans un fichier README suffit.

Voici le premier niveau du modèle C4, tiré de la section quatre point trois : un diagramme de contexte système pour la plateforme de livraison de repas. En haut figurent les trois types de personnes qui l’utilisent : les clients, le personnel des restaurants et les livreurs. Chaque flèche porte une étiquette qui dit ce qu’ils font. Au milieu se trouve la plateforme elle-même, représentée par une seule boîte. Elle prend les commandes, encaisse les paiements, affecte les livreurs et tient tout le monde informé. En dessous figurent les systèmes externes dont elle dépend : un prestataire de paiement, un service de cartographie et des services de notifications push. À ce niveau, il n’y a ni technologies ni protocoles. Ils arrivent au niveau de zoom suivant, celui des conteneurs. Et remarquez la légende. Chaque diagramme C4 a un titre et une légende, pour être compréhensible par lui-même.

Les diagrammes montrent la structure, mais ils montrent rarement le pourquoi. La section quatre point cinq traite des enregistrements de décision d’architecture, ou ADR : des enregistrements courts et datés, d’une décision chacun, avec un enregistrement complet commenté pour la plateforme de livraison. La section quatre point six montre comment un modèle de documentation comme arc42 donne à l’ensemble de la description une organisation standard, pour que les auteurs sachent quoi couvrir et les lecteurs où chercher. La section quatre point sept s’attaque au problème qui met en échec la plupart des documentations : leur obsolescence. Elle couvre l’écriture de diagrammes sous forme de texte, la publication de la documentation depuis le pipeline de build, et les habitudes de responsabilité qui la maintiennent fidèle. La section quatre point huit passe des documents aux personnes : adapter le message aux dirigeants, aux développeurs, à l’exploitation, aux équipes de sécurité et aux auditeurs, expliquer les compromis, et construire un consensus quand les avis divergent.

Chaque technique de ce chapitre sert un seul objectif : une compréhension partagée et exacte du système entre les personnes qui le construisent, l’exploitent, le financent et en dépendent. Une documentation réduite, à jour, dotée d’un responsable et placée à côté du code vaut mieux qu’un document exhaustif auquel personne ne se fie. Si vous ne retenez qu’une question de ce chapitre, que ce soit celle-ci : qui va lire ceci, et qu’en fera-t-il ?

Vous pouvez lire les sections dans l’ordre, ou aller directement à la technique dont vous avez besoin aujourd’hui. La lecture du chapitre entier prend environ trois heures. Au fil de votre lecture, comparez la façon dont chaque technique décrit la même plateforme de livraison de repas : sous forme de diagramme de contexte, de diagramme de conteneurs, de diagrammes de séquence et d’états, d’enregistrement de décision et de synthèse d’une page. Chaque section se termine par quelques questions d’autoévaluation. Répondez-y de tête avant de regarder. Quand vous serez prêt, passez le test du chapitre, facultatif : vingt questions à choix multiples et deux réponses rédigées, en quarante-cinq minutes environ. La note de réussite est de quatre-vingts pour cent.

Voilà la carte du chapitre 4. Commencez par la section quatre point un, où nous examinons à qui s’adresse la documentation, et quelle quantité vaut la peine d’être écrite. À très vite.