Documenter une architecture

Les pages qui suivent répondent à des questions d’outil : comment dessiner (C4), avec quelle notation (UML), comment justifier (ADR). Celle-ci répond à ce qui vient avant : quoi documenter, où le mettre, et qu’est-ce qui va pourrir.

Un seul constat cadre tout le reste :

Un document faux coûte plus cher qu’un document absent.

Un document absent fait perdre une heure à quelqu’un qui va lire le code. Un document faux fait prendre une mauvaise décision, avec confiance. La question n’est donc pas « combien documenter » mais « comment ne documenter que ce qui ne mentira pas ».

Classer par vitesse de péremption

C’est le critère le plus utile, et il précède tous les choix d’outil. Tout artefact de documentation appartient à l’une de ces quatre natures.

Le constat gênant : la plupart des équipes écrivent surtout la quatrième catégorie — la seule qui se périme — et négligent les trois premières, qui sont presque gratuites et ne mentent pas.

D’où un réflexe simple à prendre avant d’écrire quoi que ce soit : dans quelle catégorie tombe ce document ? Et s’il tombe dans « entretenu », est-il possible de le déplacer ailleurs ?

• Un paragraphe qui explique un choix → c’est une décision, donc un ADR.
• Un schéma dessiné à la main → c’est une vue, donc un modèle à décrire.
• Une liste de champs et de types → c’est une référence, donc à générer.

Ce qui reste après ces trois déplacements est le vrai périmètre de la documentation entretenue. Il est en général beaucoup plus petit qu’on ne l’imaginait.

Quatre formes, quatre publics

Le deuxième cadre utile s’appelle Diátaxis, formulé par Daniele Procida. Il part d’une observation : la plupart des documentations sont illisibles non pas parce qu’elles sont mal écrites, mais parce qu’elles mélangent quatre formes qui n’ont ni le même lecteur, ni le même but.

La règle qui en découle est stricte et très efficace : un document, une forme. Un README qui est simultanément un tutoriel, une référence et une justification ne sert aucun des trois lecteurs.

Appliqué à cette section : un ADR est une explication, une vue C4 est une référence, un diagramme UML de séquence est une explication ponctuelle, et un tutoriel d’architecture n’existe pas — c’est pourquoi les guides d’architecture qui commencent par « d’abord, installez… » sonnent faux.

Le squelette : arc42

C4 fournit des diagrammes, les ADR fournissent des décisions. Reste le plan du document dans lequel les ranger, et c’est ce qu’apporte arc42 : douze chapitres standardisés pour décrire une architecture.

Le tableau montre aussi que les trois outils se composent : arc42 donne le plan, C4 remplit les chapitres 3, 5 et 7, les ADR remplissent le chapitre 9, et le chapitre 12 est un glossaire de domaine.

L’architecture-as-code

C’est le principe qui traverse toute cette approche, et il tient en une phrase :

Tout artefact d’architecture vit dans le dépôt, en texte, versionné avec le code qu’il décrit.

Il s’applique à trois artefacts distincts, ce qui n’apparaît pas toujours parce qu’on l’associe à un seul outil.

depot/
  src/
  docs/
    architecture/
      workspace.dsl        le modèle : éléments, relations, vues
      adr/
        0001-….md          une décision par fichier, jamais modifiée
      guides/
        importer-un-lot.md un guide pratique, entretenu, daté
  README.md                à quoi ça sert, comment le lancer, où aller ensuite
  openapi.yaml             généré depuis le code

Trois raisons de préférer le dépôt à un wiki, et la deuxième est la seule qui compte vraiment :

Même cycle de vie que le code. Une modification d’architecture et sa documentation arrivent dans la même proposition de modification, ou pas du tout.

La revue. C’est le seul moment où la documentation est réellement lue et discutée. Un git diff sur un modèle montre l’évolution de l’architecture en trois lignes — un conteneur ajouté, une relation supprimée — et une décision d’architecture devient une proposition qu’on peut contester avant qu’elle soit appliquée. Aucun outil graphique ne permet cela, et c’est à lui seul l’argument décisif.

La survie aux migrations d’outils, qui emportent les wikis avec une régularité remarquable.

Le contrat comme documentation

La documentation la plus fiable d’une interface n’est pas un texte : c’est son contrat exécutable.

Trois propriétés le rendent supérieur à de la prose : il est généré depuis le code ou vérifié contre lui, donc il ne dérive pas ; il est testable, par des tests de contrat ; et il sert de spécification aux consommateurs, donc quelqu’un s’aperçoit immédiatement s’il est faux.

Ce que le système dit de lui-même

Une source de documentation qu’on néglige presque toujours : la production.

Les traces distribuées donnent le graphe d’appels réel, et il diffère régulièrement de celui qu’on a dessiné — un service qui en appelle un autre que personne n’avait prévu, une dépendance oubliée, un appel synchrone là où le modèle annonce de l’asynchrone. Les catalogues de services et les graphes de dépendances dérivés des traces relèvent de la même idée.

La façon juste de s’en servir n’est pas de remplacer le modèle par ce qui est observé, mais de comparer les deux : le modèle décrit ce qui devrait être, les traces ce qui est, et l’écart entre les deux est l’information intéressante. C’est le seul mécanisme de détection de dérive qui fonctionne vraiment — et à peu près personne ne le regarde.

Le minimum viable

Ce que je mettrais dans un dépôt, dans cet ordre, et rien de plus tant que ces cinq points ne sont pas faits.

1. Un README qui répond à quatre questions : à quoi sert ce logiciel, comment le lancer, comment le tester, où aller ensuite. Rien d’autre — tout le reste relève d’un lien.
2. Un diagramme de conteneurs, le niveau 2 de C4. C’est le seul document dont l’absence se paie tous les jours, et il tient en vingt lignes de DSL.
3. Un dossier docs/adr/, alimenté à partir de maintenant. Aucun rattrapage : les décisions passées sont perdues, l’admettre coûte moins que de les inventer.
4. Un glossaire du domaine. Dix termes suffisent pour commencer, et c’est le document au meilleur rapport valeur/effort de la liste.
5. Le contrat d’API généré, publié à chaque livraison.

Cinq artefacts. Un seul — le README — appartient à la catégorie qui se périme, et il fait vingt lignes.

Les pièges

Documenter pour se couvrir. Dès que la documentation devient un moyen de reporter la responsabilité, elle cesse d’être honnête : les conséquences négatives disparaissent des ADR, les risques du chapitre 11 s’évaporent.

Le wiki d’entreprise. Découplé du code, jamais relu en revue, structuré par l’organigramme plutôt que par le logiciel, et rempli de pages dont l’auteur a quitté l’entreprise.

L’exhaustivité. Un système entièrement documenté est un système dont la documentation est fausse à 40 %, sans qu’on sache quels 40 %. Mieux vaut cinq documents vrais que cinquante douteux.

Le schéma unique en A0. La « grande image d’architecture » qu’on imprime et que personne ne lit. Quatre diagrammes tenant chacun sur un écran valent infiniment mieux.

La documentation retro-générée depuis le code, présentée comme de l’architecture. Un diagramme de classes produit automatiquement sur trois cents classes n’est pas de la documentation, c’est du bruit avec une mise en page.

Ni propriétaire, ni date. Tout document de la catégorie « entretenu » a besoin des deux. Sans date, le lecteur ne sait pas s’il peut y croire ; sans propriétaire, personne ne le corrige.

Comment savoir si ça marche

Quatre signaux observables, préférables à toute auto-évaluation :

• Un nouvel arrivant devient autonome sans qu’on lui explique le système à l’oral.
• On trouve une réponse en moins de deux minutes, ou l’on sait où chercher.
• Un changement d’architecture arrive avec son diff de documentation dans la même proposition de modification.
• Personne ne dit « ah non, ça, ce n’est plus à jour ». C’est le signal le plus parlant : cette phrase signifie que la documentation est devenue un piège, et qu’il vaudrait mieux la supprimer que la laisser.

Références

• https://diataxis.fr/ — Diátaxis, par Daniele Procida ; le site est lui-même une démonstration du cadre
• https://arc42.org/overview — arc42, gabarit et exemples, en accès libre
• Philippe Kruchten, Architectural Blueprints — The 4+1 View Model, 1995
• Simon Brown, Software Architecture for Developers, volume 2 — Visualise, document and explore — le complément direct de la page C4
• https://www.writethedocs.org/guide/docs-as-code/
• https://www.openapis.org/ et https://www.asyncapi.com/