Pourquoi documenter, et dans quelle mesure

Pourquoi une architecture doit être mise par écrit

Tout système a une architecture, que quelqu’un la décrive ou non (voir la section 1.1). La description d’architecture est autre chose : les documents, diagrammes, modèles et enregistrements de décision par lesquels les gens partagent une compréhension de cette architecture. Dans une équipe de trois personnes qui travaillent côte à côte et ont écrit chaque ligne, une grande partie de la description peut rester dans leur tête. Dès que l’équipe grandit, que des personnes partent, qu’une deuxième équipe arrive, qu’un auditeur se présente ou que le système survit à ses auteurs, un savoir qui n’existe que dans les têtes devient un risque. La définition de l’architecture donnée par Ralph Johnson, la compréhension partagée des développeurs experts, contient un avertissement : une compréhension qui n’est pas écrite ne peut se partager qu’en parlant, et la parole ne passe pas à l’échelle.

Documenting Software Architectures: Views and Beyond (Paul Clements et ses collègues du Software Engineering Institute, 2e édition, 2010) cite trois usages de la documentation d’architecture, et ils restent la façon la plus claire de comprendre pourquoi elle vaut l’effort. Elle forme : elle fait découvrir le système aux nouveaux membres de l’équipe, aux relecteurs externes et aux nouveaux architectes. Elle est le principal vecteur de communication entre parties prenantes : développeurs, exploitants, équipes de sécurité et managers débattent du système à travers elle, et les décisions prises dans une réunion parviennent à ceux qui n’y étaient pas. Enfin, elle est la base de l’analyse et de la construction : elle indique à ceux qui implémentent ce qu’ils peuvent faire et ne pas faire, et c’est ce qu’examine un évaluateur qui se demande si le système atteindra ses objectifs de qualité (les méthodes d’évaluation du chapitre 11 ont besoin d’une description pour travailler).

Deux conséquences en découlent. D’abord, la documentation est un moyen, pas une fin : un document qui ne sert aucun de ces usages est du gaspillage, aussi bien mis en forme soit-il. Ensuite, c’est le lecteur qui juge si elle a fonctionné. Une description que son auteur trouve complète mais dont un nouveau venu ne peut rien faire a échoué sur le plan de la formation, et un diagramme que l’équipe d’exploitation ne peut pas faire correspondre à de vrais serveurs a échoué sur le plan de l’analyse.

Des logiciels opérationnels plus qu’une documentation exhaustive

Le Manifeste agile (2001) énonce quatre paires de valeurs, dont l’une est Des logiciels opérationnels plus qu’une documentation exhaustive. On le cite souvent comme une permission de ne rien documenter du tout. Lu en entier, le manifeste dit quelque chose de plus restreint. Ses auteurs précisent que, si les éléments de droite ont de la valeur, ils valorisent davantage ceux de gauche. Cette valeur fixe une priorité pour les cas où les deux entrent en concurrence ; elle ne rejette pas la documentation.

Ce que cette valeur rejette, c’est le projet piloté par la documentation des années 1990 : des centaines de pages de spécifications validées avant qu’une ligne de code soit écrite, considérées comme un progrès en soi, puis abandonnées dès que le code s’en écarte. Le mot qui compte est exhaustive : une documentation qui cherche à tout décrire, pour elle-même, et à laquelle on accorde plus de valeur qu’au système en fonctionnement. Rien dans le manifeste ne s’oppose à un diagramme de contexte, à un court enregistrement expliquant pourquoi l’équipe a choisi la messagerie asynchrone, ou à un runbook qui permet à l’ingénieur d’astreinte de rétablir le service à trois heures du matin.

Les praticiens ne s’accordent pas sur jusqu’où aller. Certains coachs agiles soutiennent que la conversation et les tests suffisent presque toujours, et que la documentation d’architecture écrite devient obsolète plus vite qu’elle ne rapporte. D’autres, en particulier ceux qui maintiennent des systèmes à longue durée de vie ou travaillent dans des secteurs réglementés, soulignent que les personnes qui ont le plus besoin de la documentation (les successeurs, les auditeurs, l’équipe d’exploitation) sont justement celles qui sont absentes des conversations. Les deux positions s’accordent sur l’économie sous-jacente : la documentation a un coût d’écriture, un coût de mise à jour et un coût de lecture, et elle ne vaut la peine d’être produite que là où sa valeur pour les lecteurs dépasse ces coûts.

Juste assez de documentation

L’expression de Scott Ambler « just barely good enough » (tout juste suffisant) décrit la cible : un modèle ou un document est suffisant lorsqu’il remplit son objectif pour son public, et tout effort au-delà coûte plus qu’il ne rapporte. Son idée que c’est le public, et non l’auteur, qui décide si un artefact est suffisant est le même principe que celui d’écrire pour le lecteur. George Fairbanks défend la même idée pour le travail d’architecture dans son ensemble dans Just Enough Software Architecture (2010) : en faire autant que les risques le justifient (voir la section 1.8).

La documentation juste suffisante n’est donc pas une quantité fixe. Elle croît avec la taille et la durée de vie du système, le nombre d’équipes, la rotation du personnel, le coût d’une défaillance et les exigences des régulateurs. Un prototype à deux personnes a besoin d’un README et peut-être d’un diagramme. Une plateforme de paiement exploitée par huit équipes sous réglementation financière a besoin de vues de contexte, de conteneurs et de déploiement, d’un journal des décisions remontant sur des années, de concepts de sécurité documentés et de preuves que les documents sont revus.

Un signal pratique est la question qui revient. Si les nouveaux venus posent la même question dès leur première semaine, ou si le même débat de conception ressurgit tous les quelques mois, la réponse doit être écrite. Un autre est l’erreur coûteuse : si une équipe a enfreint une règle non écrite (« ne jamais appeler le prestataire de paiement depuis l’app restaurant ») parce que personne ne la lui avait dite, cette règle relevait de l’architecture et aurait dû être écrite.

Ce qui vaut la peine d’être documenté, et ce qui ne le vaut pas

Les informations diffèrent de deux façons qui déterminent comment les documenter. La première est de savoir si elles peuvent être retrouvées à partir du code. Les noms de classes, les signatures de méthodes et les tables de base de données se lisent dans le code source à tout moment ; les raisons d’une décision, les objectifs de qualité que sert le système et les options rejetées ne le peuvent pas, car elles n’ont jamais été dans le code. La seconde est leur fréquence de changement. La finalité du système et ses principaux partenaires externes changent rarement ; la liste des classes d’un module change chaque semaine.

La documentation d’architecture écrite à la main doit se concentrer sur ce qui est à la fois important et impossible à retrouver dans le code : le contexte et la portée du système (qui l’utilise et de quels autres systèmes il dépend), ses objectifs de qualité et ses contraintes, les décisions clés et leurs raisons, la structure à gros grain (les principales parties déployables et leurs responsabilités), le déploiement sur l’infrastructure, les scénarios d’exécution importants, et les concepts transversaux que chaque partie doit suivre, comme la façon de gérer les erreurs, d’authentifier les utilisateurs et de protéger les données à caractère personnel. Cette liste est proche de la structure du modèle arc42, traité à la section 4.6.

Ce qui ne vaut pas la peine d’être écrit à la main, c’est tout ce que le code ou les outils indiquent déjà précisément et qui change souvent : les diagrammes de classes d’une base de code entière, les listes d’endpoints que contient déjà un fichier OpenAPI, ou les descriptions de chaque fonction. Lorsque de telles vues sont utiles, générez-les à partir du code source dans le pipeline de build pour qu’elles ne puissent pas dériver. Omettez aussi le contenu aspirationnel (des diagrammes de ce à quoi le système devrait ressembler, présentés comme s’il y ressemblait déjà), les comptes rendus de réunions dont le résultat est consigné ailleurs, et le texte dupliqué, qui finira par contredire sa copie.

Sept règles pour une bonne documentation

Views and Beyond énonce sept règles pour une bonne documentation. Elles valent la peine d’être connues par cœur, car presque tous les échecs de documentation enfreignent l’une d’elles.

Documentation vivante et documentation en tant que code

L’échec traditionnel de la documentation d’architecture est l’obsolescence : la description est écrite au début, le système change, et personne ne met à jour le document parce qu’il vit à l’écart du travail. Deux idées liées s’attaquent à ce problème à la racine.

La documentation en tant que code (docs as code), une pratique promue par la communauté Write the Docs, consiste à traiter la documentation comme du code source : écrite dans des formats texte comme Markdown ou AsciiDoc, conservée en gestion de versions (généralement dans le même dépôt que le code qu’elle décrit), modifiée par les mêmes pull requests, revue par les mêmes personnes, et construite et publiée par le même pipeline. On peut alors exiger qu’une pull request qui modifie la façon dont les commandes sont affectées aux livreurs mette à jour la vue d’exécution dans le même commit, et le relecteur voit les deux.

La documentation vivante, terme popularisé par le livre de Cyrille Martraire qui porte ce nom (2019), va plus loin : chaque fois que c’est possible, la documentation doit être tirée du système lui-même pour ne pas pouvoir dériver. Des diagrammes de dépendances générés à partir du code, des références d’API générées à partir de fichiers OpenAPI, des règles d’architecture vérifiées par des tests automatisés et des diagrammes générés à partir d’un modèle conservé à côté du code en sont des exemples. Le texte écrit à la main est réservé à ce qui ne peut pas être dérivé, principalement l’intention et la justification.

Aucune de ces idées ne dispense de juger de ce qu’il faut écrire. La section 4.7, Diagrammes en tant que code, présente en détail les outils et les habitudes.