Communiquer l’architecture à différents publics

Communiquer, c’est le métier

Une architecture que seul son architecte comprend a échoué, si bonne soit-elle. Les décisions façonnent ce que des dizaines de personnes construisent, exploitent, financent et auditent, et elles ne fonctionnent que si ces personnes les comprennent assez bien pour agir en conséquence et pour remarquer quand la réalité s’en écarte. C’est pourquoi le programme de l’iSAQB compte la communication de l’architecture parmi les tâches essentielles de l’architecte, et pourquoi le rôle de l’architecte décrit au chapitre 1 repose autant sur les compétences relationnelles.

Les sections précédentes de ce chapitre ont fourni la matière : vues, diagrammes C4 et UML, ADR, structure arc42 et un pipeline qui les tient à jour. Cette section porte sur l’usage de cette matière avec des personnes. La compétence centrale est la même dans toutes les situations : déterminer qui est le public, déterminer ce qu’il doit faire après vous avoir entendu, et lui donner exactement ce que cela exige, sous une forme qu’il peut assimiler. L’image de l’ascenseur de l’architecte (architect elevator) de Gregor Hohpe (The Software Architect Elevator, 2020) résume cette amplitude : l’architecte circule entre la salle du conseil, où la stratégie se définit en termes métier, et la salle des machines, où les systèmes sont construits, et doit être compris à chaque étage.

S’adapter au public

Chaque public a ses propres préoccupations, exactement au sens des parties prenantes et préoccupations, ainsi que son propre vocabulaire et sa propre capacité d’attention. Le tableau est un point de départ ; la vraie compétence consiste à se demander, avant de préparer quoi que ce soit : que va décider ou faire différemment cette personne après cette conversation ?

Deux habitudes aident avec tous les publics. Commencez par la réponse. Les lecteurs pressés doivent connaître la conclusion dès la première phrase, puis les raisons qui l’étayent, puis le détail ; c’est la structure que Barbara Minto enseignait aux consultants sous le nom de Pyramid Principle (principe de la pyramide), et c’est la même idée que la pyramide inversée de Fowler pour les ADR. Employez leurs mots. Pour une directrice financière, cohérence à terme n’est que du bruit ; le restaurant voit une nouvelle commande jusqu’à deux secondes après le client, et rien n’est perdu est un fait qu’elle peut évaluer.

Expliquer les compromis

L’essentiel de la communication architecturale consiste, au fond, à expliquer un compromis. Les non-spécialistes se méfient des recommandations qui semblent n’avoir aucun inconvénient, et ils ont raison. Une structure claire, employée de façon constante, rend les compromis faciles à suivre : les options (y compris ne rien faire), les critères qui comptent pour ce public, la façon dont chaque option s’en sort, la recommandation et ses conséquences, y compris ce à quoi vous renoncez. C’est l’anatomie d’une décision vue au chapitre 1 et le contenu d’un ADR, remodelés pour un auditoire.

Le résumé d’architecture en une page

Tout système gagne à avoir un résumé d’architecture en une page : une page unique qu’une nouvelle recrue, un dirigeant ou un relecteur d’une autre équipe peut lire en cinq minutes. Il ne remplace pas la documentation complète, il en est la porte d’entrée. Une structure utile est la suivante : ce que fait le système et pour qui (deux phrases) ; les trois principaux objectifs de qualité ; un diagramme de contexte système ; un diagramme de conteneurs ou une liste des principaux blocs de construction ; les cinq décisions environ qui façonnent tout le reste (une ligne chacune, avec un lien vers les ADR) ; les principaux risques ; et où en savoir plus. La page arc42 allégée de arc42 et modèles est un tel résumé.

L’exercice qui consiste à faire tenir l’architecture sur une page est précieux en soi. Si les idées principales ne peuvent pas être exposées en une page, elles ne sont probablement pas claires non plus pour l’équipe.

Raconter : suivre une requête

On retient mieux les histoires que les structures. Une technique efficace pour expliquer n’importe quel système consiste à suivre une requête : choisissez un seul événement, concret et important, comme un client qui passe commande, et parcourez pas à pas ce qui lui arrive à travers l’architecture. Un diagramme statique de boîtes montre ce qui existe ; le récit montre pourquoi cela existe et comment les parties coopèrent. Il fait aussi apparaître naturellement les moments intéressants : où le client attend, où les données franchissent une frontière de confiance, ce qui se passe si le prestataire de paiement est lent.

Choisissez le récit en fonction du public. Pour les développeurs, le chemin nominal, puis une défaillance (maintenant, le prestataire de paiement dépasse son délai). Pour l’exploitation, la défaillance et la reprise. Pour les dirigeants, l’expérience du client, avec seulement les moments qui comptent pour l’activité. Numérotez les étapes sur le diagramme pour pouvoir les montrer du doigt, et gardez le même diagramme à l’écran pendant que vous parlez plutôt que de passer d’une diapositive à l’autre.

Bien utiliser le tableau blanc et le croquis

Une grande partie de la communication architecturale se fait en direct, devant un tableau blanc ou sur un canevas partagé en ligne, et quelques habitudes rendent les croquis bien plus utiles. Dites ce que vous dessinez avant de le dessiner (ceci est le niveau conteneurs : les éléments que nous déployons séparément), afin que le public connaisse le niveau d’abstraction. Commencez par le contexte : les utilisateurs et les systèmes externes sur les bords, puis l’intérieur. Libellez chaque boîte et chaque ligne au fur et à mesure, y compris le sens et ce qui circule ; une flèche sans libellé sera lue de trois façons différentes par trois personnes. Dessinez une petite légende dans un coin quand vous utilisez plus d’un type de ligne ou de boîte. Laissez de la place, car les meilleures idées arrivent en pleine discussion et ont besoin d’un endroit où aller.

Les croquis sont des outils de réflexion, faits pour être jetés, mais pas les conclusions. Photographiez le tableau et, dans la journée, transformez tout ce qui comptera en vrai diagramme, en ADR ou en modification de la documentation. Simon Brown, créateur du modèle C4, a observé que les diagrammes au tableau blanc de nombreuses équipes sont des boîtes et des traits ambigus précisément parce qu’il leur manque un ensemble d’abstractions convenu ; utiliser les niveaux C4 au tableau blanc est l’un des moyens les plus simples d’y remédier.

Documents de conception et RFC

De nombreuses organisations d’ingénierie utilisent un document de conception écrit, souvent appelé RFC (request for comments, appel à commentaires), pour proposer une modification importante avant de la construire. Le nom fait écho à la série des RFC d’Internet, qui a commencé avec la RFC 1 de Steve Crocker en avril 1969. L’auteur expose le problème, le contexte, les objectifs et les non-objectifs, la conception proposée, les alternatives envisagées et les préoccupations transversales comme la sécurité, la confidentialité et l’observabilité ; le document est diffusé aux personnes concernées, qui le commentent par écrit ; puis il est approuvé ou révisé. La description très lue des design docs chez Google par Malte Ubl (2020) énumère exactement ces sections et suggère dix à vingt pages pour les grands projets, et une à trois pages pour les petits mini design docs. Gergely Orosz a décrit comment Uber a utilisé un processus de RFC dès ses premières années pour diffuser les connaissances et détecter les problèmes tôt (2018).

Amazon pousse l’écrit plus loin : sa lettre aux actionnaires de 2017 explique que l’entreprise n’utilise pas de présentations à base de diapositives en réunion, mais des mémos de six pages à structure narrative, que les participants lisent en silence au début. L’avantage commun à toutes ces pratiques est qu’écrire oblige à penser clairement, que les commentaires écrits permettent aux collègues plus discrets ou à distance de contribuer, et que le document devient une trace. Les risques sont eux aussi communs : de longs documents que personne ne finit, des processus de relecture qui deviennent des barrières bureaucratiques, et des documents de conception jamais mis à jour après la mise en œuvre.

Documents de conception et ADR se complètent. Un document de conception explore un problème et propose une conception complète, couvrant souvent plusieurs décisions ; une fois qu’il est approuvé, les décisions importantes qu’il contient sont consignées sous forme d’ADR, plus courts, permanents et indexés. Une règle raisonnable : le document de conception pour réfléchir et convaincre, l’ADR pour se souvenir.

Présenter lors d’une revue d’architecture

Une revue d’architecture est une réunion au cours de laquelle d’autres personnes expérimentées examinent une conception pour en trouver les risques avant qu’ils ne deviennent coûteux. Les méthodes structurées comme l’ATAM et les revues plus légères sont traitées au chapitre 11 : revues légères ; il s’agit ici de bien présenter. Envoyez le matériel au moins deux jours à l’avance : le résumé en une page, les diagrammes clés, les ADR pertinents et les scénarios de qualité. Dites dès le début ce que vous attendez de la revue : une approbation, une liste de risques ou un choix entre deux options. Présentez les facteurs avant la conception, car un relecteur ne peut pas juger une conception sans savoir quelles qualités elle doit atteindre. Déroulez un ou deux scénarios avec la technique qui consiste à suivre une requête, y compris une défaillance. Montrez les compromis que vous avez faits et les risques que vous connaissez ; un relecteur qui trouve un risque que vous avez déjà listé vous fait davantage confiance, pas moins. Consignez chaque point soulevé, avec un responsable, et envoyez la liste ensuite.

Règles de conception visuelle des diagrammes

Les diagrammes communiquent avant que quiconque ait lu un mot, leur conception visuelle compte donc. Les règles ci-dessous s’inspirent des recommandations de notation C4 présentées dans le modèle C4 et de la conception de l’information en général. Le diagramme avant/après les applique aux mêmes cinq éléments.

Gérer les désaccords et construire un consensus

Les désaccords sur l’architecture sont normaux et sains : ils signifient généralement que les gens voient des risques différents. Le but n’est pas de gagner, mais d’aboutir à une décision que les personnes qui devront vivre avec comprennent et soutiendront. Plusieurs pratiques aident.

Distinguez les intérêts des positions. Nous devons utiliser Kafka est une position ; je crains que nous perdions des événements pendant les déploiements est un intérêt, et un intérêt peut souvent être satisfait de plusieurs façons. Convenez des critères avant de comparer les options, comme dans une matrice de décision pondérée ; la plupart des discussions animées sont en réalité des désaccords sur ce qui compte, et elles s’apaisent dès que c’est explicite. Levez l’incertitude par des preuves : un spike (investigation limitée dans le temps) de deux jours ou un test de charge tranche bien des débats que les réunions ne peuvent pas régler. Mettez-le par écrit : un ADR proposé ou un document de conception permet à chacun de commenter à son rythme et donne la parole aux collègues plus discrets.

Visez le consentement plutôt que l’unanimité. La RFC 7282 de l’IETF (Pete Resnick, 2014) décrit le consensus approximatif : une décision est atteinte quand chaque objection a été traitée, c’est-à-dire examinée et a reçu une réponse, sans forcément avoir été prise en compte. Demander y a-t-il quelqu’un qui ne peut pas vivre avec cela, et pourquoi ? fait apparaître les points bloquants plus vite que de demander si tout le monde est d’accord. Quand le consensus n’est pas possible, quelqu’un doit décider, et il faut savoir à l’avance qui. La lettre aux actionnaires de Jeff Bezos de 2016 a popularisé le disagree and commit (exprimer son désaccord, puis s’engager) : chacun exprime ouvertement son désaccord, puis s’engage pleinement dans la décision une fois qu’elle est prise. Consignez le désaccord et ses raisons dans l’ADR ; si ceux qui n’étaient pas d’accord ont raison, l’enregistrement indique ce qu’il faut réexaminer et pourquoi.

Deux dérives méritent une mise en garde. L’architecte qui gagne chaque discussion par ancienneté n’entend plus parler des problèmes. L’équipe qui ne peut pas décider sans unanimité laisse des décisions importantes se prendre par défaut, ce qui est l’inverse du dernier moment responsable.