Architecturer la documentation : organiser une documentation d’architecture logicielle fiable

Temps de lecture estimé : 9 minutes 

En résumé 

Une documentation d’architecture fiable ne repose pas sur un outil unique, mais sur une organisation claire : chaque information répond à un besoin, dispose d’une source de référence et évolue au rythme de ce qu’elle décrit.

Un diagramme C4, un ADR, une page Confluence ou une documentation proche du code ne jouent donc pas le même rôle.

Le bon support dépend des utilisateurs visés, du niveau de détail attendu, de la fréquence d’évolution de l’information et de son besoin de conservation.

L’enjeu est de savoir où placer chaque information, quelle source fait foi et qui est responsable de sa maintenance.

Introduction

Dans un précédent article, nous avons vu qu’une stratégie de branching ne devait pas être choisie par habitude, mais en fonction des contraintes du produit.

La documentation d’architecture rencontre exactement le même problème.

Confluence, Markdown, ADR, modèle C4, Mermaid, Documentation as Code… les supports et les pratiques permettant de documenter un système se multiplient.

La difficulté n’est pourtant pas seulement de choisir un outil. Elle est surtout de savoir quelle information doit être documentée, où elle doit vivre, qui en est responsable et comment la maintenir fiable dans le temps.

Un architecte, un développeur, un exploitant ou un nouvel arrivant ne cherchent pas nécessairement la même information. De la même manière, une décision structurante prise il y a trois ans n’a pas le même cycle de vie qu’un diagramme détaillant un flux technique amené à évoluer régulièrement.

Le modèle C4 et les ADR constituent par exemple deux approches complémentaires pour représenter un système et conserver ses décisions d’architecture. Leur utilisation détaillée est déjà présentée dans l’article Documenter l’architecture logicielle avec C4 et ADR Ici, l’objectif est de prendre davantage de recul : comment organiser ces différentes formes de documentation au sein d’un même système documentaire ?

La vraie question devient alors :

Comment organiser la documentation pour que chacun sache où trouver une information fiable et comment la maintenir dans le temps ?

Documenter avec un outil par habitude : un biais à éviter

Dans beaucoup d’équipes, la documentation se construit progressivement autour des outils disponibles.

Confluence devient « l’endroit où l’on documente ». Les diagrammes sont créés dans Draw.io. Les README accueillent les informations techniques. Puis apparaissent quelques fichiers Markdown, des schémas Mermaid ou PlantUML, parfois des ADR.

Chaque choix peut être pertinent individuellement. Le problème apparaît lorsque personne ne sait réellement quelle information doit être placée où.

Face à cette dispersion, le réflexe consiste souvent à chercher à tout centraliser dans un outil unique.

Mais centraliser ne signifie pas nécessairement mieux documenter.

Une décision d’architecture, une vision globale du système ou une procédure technique n’ont pas les mêmes contraintes de consultation et de maintenance.

Le problème n’est donc pas nécessairement la multiplicité des outils. Le problème est l’absence de règles permettant de savoir quel rôle chacun d’eux doit jouer.

Quand la documentation ne reflète plus la réalité

Lorsqu’une documentation contredit le système, il faut revenir aux sources les plus proches de son fonctionnement réel : le code, la configuration ou encore l’environnement déployé.

Ces sources permettent de comprendre ce qui existe aujourd’hui, mais elles ne racontent pas toujours pourquoi le système a été conçu ainsi, quelles options ont été envisagées ou quels compromis ont été acceptés.

Une documentation mal organisée ne pose pas seulement un problème de confort. Elle finit par affecter directement la compréhension du système et la capacité d’une équipe à le faire évoluer. Les travaux de DORA sur la qualité documentaire identifient la documentation interne comme une capacité pouvant renforcer l’efficacité des autres pratiques techniques d’une organisation. Sa qualité repose notamment sur des critères comme la clarté, la facilité à retrouver l’information et sa fiabilité.

Les symptômes sont souvent faciles à reconnaître :

• Plusieurs documents décrivent différemment le même système
• Un nouvel arrivant ne sait pas par où commencer
• Certaines décisions importantes ne sont connues que par quelques personnes
• Des diagrammes continuent d’être consultés alors qu’ils ne reflètent plus la réalité
• Personne ne sait clairement quelle information fait foi

Le risque n’est pas seulement l’absence de documentation. Une documentation obsolète peut être plus trompeuse : elle donne l’impression que l’information est fiable alors que le système a déjà évolué.

Le rythme d’obsolescence varie fortement selon le type d’information. Une décision d’architecture peut rester pertinente plusieurs années, tandis qu’un flux technique ou une documentation d’API peut devenir incorrect après quelques évolutions seulement.

Une page vieille de deux ans peut donc toujours être juste, tandis qu’une documentation récente peut déjà être dépassée.

La date de dernière modification n’est donc pas, à elle seule, un indicateur de fiabilité. Ce qui compte également, c’est tout ce qui a changé depuis.

Le rythme d’évolution de l’information devient donc lui-même un critère de conception de la documentation.

Recentrer autour du besoin

Avant de choisir un outil, il est plus pertinent de commencer par comprendre le besoin auquel la documentation doit répondre.

Ce besoin change selon le lecteur : un nouvel arrivant cherche une vue d’ensemble, un développeur le détail d’un flux, un exploitant les dépendances et les mécanismes de déploiement, tandis qu’un architecte peut vouloir retrouver le contexte d’une décision prise plusieurs années auparavant. Ces informations peuvent également être exploitées par des assistants ou agents IA, qui dépendent eux aussi de contenus structurés, explicites et reliés à des sources de référence fiables.

On peut ainsi appliquer à la documentation une logique proche de celle d’un produit : identifier ses utilisateurs, comprendre leur parcours et déterminer à quel moment ils ont besoin de chaque information.

Une première étape consiste donc à déterminer ce que le lecteur cherche à faire avec la documentation.

L’approche Diátaxis distingue quatre formes de documentation :

• Les tutoriels pour apprendre en étant guidé
• Les guides pratiques pour réaliser une tâche précise
• Les références pour consulter une information précise
• Les explications pour comprendre un concept ou une décision

Cette grille aide à définir la nature du contenu à produire. Un tutoriel n’est pas conçu comme une référence technique, de la même manière qu’un guide pratique ne répond pas au même besoin qu’une explication d’architecture.

Mais cela ne suffit pas à déterminer où la documentation doit vivre ni comment elle doit être maintenue. Il faut également prendre en compte plusieurs contraintes :

• Le public : qui va consulter cette information ?
• Le niveau de détail : a-t-on besoin d’une vision globale ou d’une représentation technique fine ?
• La fréquence d’évolution : cette information change-t-elle plusieurs fois par semaine ou seulement lors d’une évolution structurante ?
• Le besoin de conservation : faut-il seulement connaître l’état actuel du système, ou conserver cette information pour comprendre son évolution dans le temps ?
• La proximité avec le code : peut-elle devenir incohérente si elle évolue séparément du système ?
• La responsabilité : qui est chargé de maintenir ou de valider cette information ?

Ces deux lectures sont complémentaires : Diátaxis aide à déterminer quelle forme doit prendre la documentation, tandis que ces critères permettent de choisir où elle doit vivre et comment elle doit être maintenue.

Une décision d’architecture et une documentation d’API n’ont donc ni le même objectif, ni le même rythme d’évolution, ni les mêmes besoins de conservation.

Une documentation qui décrit l’état actuel du système doit évoluer avec lui. Une API, un flux technique ou une configuration doivent donc idéalement être mis à jour dans le même cycle que ce qu’ils décrivent.

À l’inverse, une documentation qui explique pourquoi le système est conçu ainsi doit surtout rester accessible et compréhensible dans le temps. C’est notamment le cas des décisions d’architecture ou des vues globales du système.

Le choix de l’outil devient alors une conséquence du besoin, et non son point de départ.

Construire un système documentaire cohérent

Ces approches ne sont pas de même nature et ne cherchent pas à se remplacer. Le modèle C4 propose une manière de visualiser l’architecture, les ADR conservent le contexte des décisions, la Documentation as Code applique des pratiques issues du développement à la documentation, tandis qu’un wiki organise et diffuse la connaissance.

C’est justement leur complémentarité qui permet de répondre à des besoins différents.

Modèle C4 : comprendre le système

 Le modèle C4 permet de proposer plusieurs niveaux de lecture d’un système, depuis sa place dans son environnement jusqu’à ses composants internes.

Son intérêt dans une stratégie documentaire est de fournir des vues adaptées au niveau de compréhension recherché, sans imposer le même niveau de détail à tous les lecteurs.

Il ne cherche cependant pas à tout documenter : il donne une vision structurée de l’architecture, mais ne conserve ni le contexte des décisions ni les procédures permettant d’exploiter le système.

À retenir : le modèle C4 est particulièrement adapté pour comprendre la structure du système.

Pour approfondir : Modèle C4 - Site officiel

ADR : conserver les décisions

Les ADR (Architecture Decision Records) servent à conserver les décisions d’architecture structurantes.

Leur objectif n’est pas de décrire le système, mais d’expliquer pourquoi un choix a été fait : dans quel contexte, quelles options ont été envisagées et quelles conséquences ont été acceptées.

Courts et ciblés, ils permettent de retrouver plusieurs mois ou années plus tard le contexte d’une décision qui aurait autrement pu rester dans la mémoire de quelques personnes.

À retenir : les ADR sont particulièrement adaptés pour conserver les décisions d’architecture et leur contexte.

Pour approfondir : Architectural Decision Records

Documentation as Code : rester proche du code

Certaines informations techniques évoluent au même rythme que le système : flux applicatifs, documentation d’API, exemples d’usage ou procédures liées à un composant.

La Documentation as Code consiste à traiter la documentation avec des pratiques proches de celles du code : formats texte, versionnement, revue et automatisation. Maintenue au plus près du système qu’elle décrit, elle peut évoluer dans le même cycle que l’implémentation.

Cette proximité réduit le risque de divergence, même si elle peut rendre l’information moins accessible à des publics éloignés du dépôt.

Concrètement, une description OpenAPI peut servir de source de référence pour une API HTTP et alimenter une documentation générée. Dans un projet .NET, DocFX peut produire un site documentaire à partir du code, des commentaires XML et de fichiers Markdown. Dans d’autres contextes, MkDocs permet de générer un site à partir de contenus Markdown. Ces sites peuvent ensuite être publiés automatiquement depuis le dépôt avec GitLab Pages ou GitHub Pages.

À retenir : la Documentation as Code est particulièrement adaptée aux informations techniques qui peuvent être versionnées, vérifiées ou générées avec le système.

Wiki / Confluence : partager la connaissance

Les wikis, espaces Confluence ou portails documentaires sont particulièrement utiles pour rendre la connaissance accessible à un large public.

Ils peuvent servir à organiser des parcours de lecture, documenter des processus transverses et relier différentes sources :

• Documentation du système
• ADR
• Dépôts de code
• Procédures
• Informations partagées entre équipes

Leur principal risque est de devenir à leur tour un espace où s’accumulent des contenus redondants ou obsolètes.

Un wiki est donc surtout utile comme portail permettant d’organiser et de relier les différentes sources de connaissance.

À retenir : les wikis et espaces Confluence sont particulièrement adaptés pour rendre la connaissance accessible et navigable.

En pratique : quel support pour quel besoin ?

• Besoin de comprendre la structure du système → modèle C4
• Besoin de conserver le contexte d’une décision → ADR
• Information technique qui évolue avec le système → Documentation as Code
• Besoin d’organiser et d’orienter vers les différentes sources → Wiki / Confluence

Ces approches ne sont pas exclusives : un même système peut s’appuyer sur plusieurs d’entre elles, chacune pour un besoin différent.

Comment remettre de l’ordre ?

Ces exemples montrent que le problème n’est pas forcément d’avoir plusieurs outils.

Le problème apparaît lorsque personne ne sait clairement quelle information doit vivre où, quelle source fait foi et comment elle doit être maintenue dans le temps.

Remettre de l’ordre ne signifie pas nécessairement tout migrer vers un nouvel outil. Une première démarche peut consister à :

1.  Identifier les emplacements existants et distinguer les informations encore utiles de celles qui sont devenues obsolètes.
2.  Définir une source de référence pour chaque type d’information, afin de savoir où chercher et d’éviter les doublons.
3. Attribuer une responsabilité de maintenance, puis intégrer la mise à jour de la documentation au cycle de ce qu’elle décrit.

Dans l’exemple précédent, cela peut se traduire ainsi :

• Confluence peut devenir le point d’entrée vers la connaissance partagée
• La Documentation as Code peut rapprocher les procédures techniques du système qu’elles décrivent
• Des ADR peuvent conserver les décisions structurantes prises en équipe
• Des vues C4 peuvent offrir une compréhension commune du système sans imposer la lecture de documents de plusieurs dizaines de pages

La cohérence documentaire ne vient donc pas du fait que toute l’information se trouve au même endroit, mais du fait que chacun sait où chercher l’information dont il a besoin.

Architecturer la documentation consiste justement à définir ces rôles : quelle information doit vivre où, quelle source fait foi et comment les différents supports s’articulent entre eux.

Conclusion

Architecturer la documentation ne consiste ni à produire toujours plus de documents, ni à chercher l’outil unique capable de tout contenir.

Il s’agit plutôt d’organiser un ensemble de sources complémentaires : rapprocher du système ce qui évolue rapidement, conserver le contexte des décisions structurantes et offrir des vues adaptées à ceux qui doivent comprendre ou faire évoluer l’architecture.

Une vue C4, un ADR, une documentation proche du code ou un espace Confluence répondent à des usages différents.

Comme pour la stratégie de branching, il n’existe pas de solution universelle. Le bon choix dépend du contexte et de ceux qui devront utiliser cette connaissance.

Une architecture que personne ne peut expliquer, dont les décisions ont été oubliées et dont la documentation ne reflète plus la réalité finit par devenir une architecture subie.

Documenter l’architecture, c’est donc construire et entretenir la mémoire collective du système.

Le meilleur système documentaire n’est pas celui qui contient tout. C’est celui qui permet de savoir où chercher, à quelle information faire confiance, pourquoi le système est ainsi et comment le faire évoluer.

A propos de l'auteur 

Basée à l’agence de Grenoble, Lou BEGE est ingénieure .NET et intervient depuis quatre ans sur la conception, l’évolution et l’industrialisation de systèmes d’information complexes dans le secteur de l’énergie. Elle s’intéresse particulièrement à l’architecture logicielle, à la qualité des pratiques de développement, à la documentation ainsi qu’aux sujets DevOps et CI/CD.
Cet article prolonge sa réflexion entamée dans Stratégie de branching Git sur les choix techniques qui ne devraient jamais se faire par habitude.
Tous les articles de Lou Bégé · Profil LinkedIn

Pour aller plus loin

Documentation d'architecture

• Modèle C4 - Les différents types de diagrammes
• Modèle C4 - Outils et approches de modélisation
• LikeC4 — Modéliser une architecture C4 as Code

Architecture Decision Records

• ADR Templates — Exemples de structures
• MADR — Markdown Architectural Decision Records

Documentation as Code

• Write the Docs — Docs as Code
• Write the Docs — Software Documentation Guide
• MkDocs — Documentation officielle
• GitLab Pages — Documentation officielle
• GitHub Pages — Documentation officielle