Meetup Arkup Juin 2025
https://meetup-arkup-juin-2025.florat.net/
© 2025 Bertrand Florat – CC BY-SA 4.0

Le support est disponible à :

https://meetup-arkup-juin-2025.florat.net/

ou simplement :

https://florat.net/

Sondage : Documentation as Code

Qui dans la salle…

• A déjà entendu parler de "documentation as code" ?
• Documente encore principalement avec des outils bureautiques ?
• Utilise un outil comme Asciidoc, Markdown, PlantUML, Antora, MkDocs… ?
• Génère de la doc as code (depuis du code ou des diagrammes)
• A intégré la doc dans un CI/CD, ou dans une PR/MR comme du code ?

Agenda (1H)

• 0 - Les enjeux de la documentation (générale et d'architecture)
• 1 - Les challenges de la documentation traditionnelle
• 2 - La documentation d'architecture As Code
• 3 - Les challenges de la doc As Code
• 4 - Take-away & perspectives

0 — Les enjeux de la documentation

(en général et en architecture en particulier)

Temps passé par un·e architecte à produire de la documentation

• Conception & réflexions techniques : 30–40 %
• Rédaction de documentation : 20–30 % (15 % sur projets très agiles, 40 % dans les secteurs très réglementés)
• Réunions & arbitrages : 20–30 %
• Communication & vulgarisation : 10–15 %
• Veille technologique : 5–10 %

Le ROI de la documentation

• Une activité qui dérape très facilement :

  • Documentation inutile, hors sujet, inmaintenable
  • Coût élevé, retour hypothétique voire négatif
  • En Lean, on appelle ça du Muda (gaspillage)

• Écrire une doc, c’est un engagement :

  • Beaucoup aiment écrire, peu souhaitent maintenir
  • Écrire implique de maintenir dans la durée

Pourquoi documenter ?

Communiquer des informations importantes

• Dans l’espace :
  • Organisations distribuées, télétravail, décalage horaire…
• Mais surtout dans le temps :
  • Pour les autres : TMA, futurs développeurs, architectes…
  • Pour soi-même dans 6 mois
  • Pour les transferts de compétences, etc.

Documenter pour avancer et cranter les sujets

• Moins de malentendus ➔ économies de temps, d’argent et de frustrations
• Tracer les choix et leurs raisons (ex. : ADR) ➔ éviter de reposer sans cesse les mêmes questions
• Economiser du temps et tester la motivation en renvoyant d'abord sur la doc

Ce que la documentation doit contenir

• TOUT ce qui est nécessaire, mais QUE ce qui est nécessaire

• Tests de Litmus : Dois-je documenter ?

  • Une personne externe compétente dans le domaine a-t-elle besoin d’explications complémentaires au code/écrans ? Si non ➔ pas de doc
  • Documenter essentiellement ce qui ne peut pas être deviné (ex. : respect d’une réglementation)
  • Répondre à la plupart des « WTF » d’une nouvelle personne sur le projet
  • Est-ce que je l’afficherais au mur dans l’open space ?

Et ne doit pas :

• Contenir du bullshit :

  • Historique, détails inutiles, règles de l’art, éléments vagues ou trop généraux

• Répéter (principe DRY ) :

  • Préférer référencer les documents existants

• Contenir des informations éphémères

• Compenser du code peu explicite (voir Clean Code / Screaming Architecture )

• Être inadaptée à son audience

Petit exemple fonctionnel

Une application d’état civil permet de saisir les dates de naissance avec trois champs entiers et non pas un Date Picker

WTF ????

Que doit contenir (ou pas) la doc dans ce cas ?

Avez-vous un problème de doc ? Comptez les... :

 "Ça doit être quelque part dans Confluence…"

 "Je l’ai fait, mais je ne sais plus comment…"

 "Tu peux demander à Maurice, c’est lui qui sait…"

 "Ah oui, le guide de DEV… mais il n’est plus à jour depuis 2021…"

Bonne documentation

• Accessible : trouvable en deux clics ou via une recherche simple
• Pertinente : adaptée au public (développeur, ops, manager…)
• Actionnable : apporte des exemples concrets, des commandes, des extraits de code
• Vivante : maintenue à jour, intégrée dans les cycles de développement

Mauvaise documentation

• Inaccessible : fichiers perdus, wiki abandonné…
• Encyclopédique : trop de détails inutiles, illisible
• Vague : « Il faut configurer le proxy »… Mais comment ?
• Périmée : décrit un monde qui n’existe plus

La documentation vivante (Cyrille Martraire)

« Une documentation fiable, utile, et toujours à jour. »

Principes clés

• Fiable : toujours en phase avec le logiciel livré, à tout moment
• À faible effort : facile à maintenir, même lors de changements
• Collaborative : favorise les échanges et le partage de savoir
• Porteuse de sens : met en lumière les enjeux, déclenche des retours et aide à mieux décider

L'importance de L'UL (Ubiquitus Language)

• UL issu du Domain-Driven Design (DDD) d’Eric Evans
• Objectif : un langage partagé entre développeurs, experts métier, testeurs et architectes
• Utiliser les mêmes termes métier partout (code, doc, tests, diagrammes)
• Éviter les synonymes et les variations
• Favorise la compréhension entre les parties prenantes

Quid de la documentation d’architecture en particulier ?

• Tout ce qui a été dit précédemment s’applique aussi aux documents d’architecture

• Préférer les diagrammes au texte (UML, C4, BPMN, ArchiMate en particulier)

• Ne pas hésiter à commenter les diagrammes (directement dans le diagramme ou dans le document parent avec des détails pertinents : tips / warnings)

• Être honnête :

  • Lister les hypothèses d’architecture et études en cours dans un chapitre « Points non statués » pour chaque vue
  • L’incertitude doit être affichée, pas masquée

Les documentations principales de l’architecte

• Dossier d’Architecture (DA)
  Vue d’ensemble des choix, contextes, exigences et contraintes

• ADR – Architecture Decision Records
  Journal des décisions d’architecture, horodatées et justifiées

• Suivi des points d’architecture
  Comptes-rendus des réunions, discussions et arbitrages techniques

• Études techniques (sécurité, performance, etc.) et bilans de POC
  Analyses approfondies pour justifier ou évaluer des solutions

• Supports de présentation
  Slides pour comités d’architecture, parties prenantes, équipes

Les diagrammes : anti-patterns principaux

• Mélange de niveaux d’abstraction différents

• Trop d’éléments (~ > 20)

• Métaréprésentations floues :

  • Pas de légende ou difficile à comprendre
  • Trop de couleurs, formes, types de flèches

• Flèches à double sens (on ne sait pas qui initie la communication)

Les diagrammes : bonnes pratiques principales

• Métaréprésentations simples, niveau d’abstraction homogène, nombre raisonnable d’éléments

• Actions explicites sur les flèches

  • Indiquer le type d’échange ou de flux
  • Indiquer la nature du flux (lecture / écriture / exécution), si utile

Exemple C4 : diagramme de container

1 - Le problème avec la documentation traditionnelle

Ce que j’entends par « documentation traditionnelle »

Répond à la plupart de ces critères :

• Documents bureautiques binaires : Word, PDF, PowerPoint… (même partagés)

• Statique et figée dès sa publication

• Mise à jour fastidieuse → risque élevé de devenir rapidement obsolète

• Traçabilité des modifications faible ou manuelle

• Peu intégrée aux outils et processus de développement

• Existe uniquement comme livrable d’un processus, pas orientée produit

Faible évolutivité et traçabilité

• Peu ou pas de collaboration active avec les parties prenantes

  • Décisions prises en silo
  • Peu adapté aux revues par pair (suivi des modifications mais pas de MR)

• Faible traçabilité des évolutions, en particulier sur les diagrammes (binaires)

• Difficulté en cas de renommage ou de réorganisation

  • Références croisées cassées
  • Renommages / refactorings risqués et peu pratiques sur un lot de documents

Une doc moins adaptée aux LLM

• Documents bureautiques peu formels : structure faible, pas de validation possible du contenu ou des métadonnées (type Git hooks)

• Perte de sens en cas d’entraînement de LLM

  • Contenu essentiellement binaire, peu structuré, plus difficile à exploiter par l’IA
  • Plus difficile de faire générer du contenu

Plus de risques de fuite

• Aspiration de drives partagés
• Export et diffusion incontrôlés des fichiers
• Métadonnées oubliées (ex. : devis pour un autre client…)
• Volumétrie importante (surtout en cas de multi-versions)

Des efforts de mise en page importants

• Trop de temps consacré à la mise en page du texte et au polissage des diagrammes
• Esthétique privilégiée au détriment du fond
• Création de diagrammes figés nécessitant de lourdes reprises pour toute modification
• Peu de réutilisation et pas de factorisation des représentations

2 – La Documentation As Code

Documentation traditionnelle vs As Code

Traditionnelle	Vivante / As Code
Fichiers Word / PDF statiques	Texte versionné (Git)
Peu ou pas de traçabilité	Historique, tags et auteurs tracés
Rapide obsolescence	Mise à jour continue
Non intégrée aux workflows	Intégrée dans le cycle DevOps
Lecture linéaire	Navigation hypertexte
Diagrammes figés	Diagrammes générés à partir du code
Peu collaborative	Collaboration via revues de code / MR/PR

En résumé : passer d’un document que l’on subit à un actif vivant et maîtrisé du projet

Utiliser Git pour documenter efficacement

• Historique complet : chaque modification est enregistrée
• Tags : versionnez les jalons de votre documentation (v1.0, v2.0...)
• Blame : savoir qui a écrit quoi, et quand
• Diffs : comparaison facile entre deux versions
• Revue via merge request / pull request
• Revenir dans le temps : checkout d’une version antérieure

Et au-delà de Git de base

• CI/CD pour valider / publier automatiquement votre doc (PDF, HTML…)
• Git hooks : automatiser la mise à jour d’index ou de métadonnées
• Traçabilité / conformité via signature GPG sur commits/tags (utile dans les environnements sensibles)

L’intérêt des langages de balisage légers : AsciiDoc / Markdown

• Lisibles en brut : pas besoin d’outil pour lire ou modifier
• Simplicité : syntaxe intuitive pour écrire vite
• Faciles à générer : ex. : spécifications exécutables, rapports de tests Spock
• Faciles à versionner : parfait pour Git (diffs propres, pas de binaire)
• Bonne Intégration sur les plateformes : disponible de base sur Gitlab, Github...
• Extensibles : AsciiDoc permet des blocs structurés (admonitions, macros, includes…)

Pourquoi AsciiDoc pour la doc technique avancée ?

• Structure riche : sections, blocs, tableaux complexes
• Macros & includes : contenu réutilisable, factorisable
• Table des matières (TOC), glossaires, bibliographies
• Admonitions : NOTE, TIP, CAUTION, etc.
• Diagrammes intégrés (avec plugins): PlantUML, Mermaid…
• Sorties variées : HTML5, PDF, DocBook…

Quel outil pour quel usage ?

• Docusaurus : produit/API, design et navigation moderne
• Antora : doc d'archi, microservices, équipes distribuées
• MkDocs : doc rapide à mettre en place, mono-repo
• AsciiDoc seul : doc technique avancée, sans framework

Antora : plateforme de doc modulaire

• Organisation par composants, versions, modules
• Multi-dépôts Git : chaque équipe gère sa doc dans son propre repo
• Mise à jour automatique des sources
• Navigation unifiée sur un portail de documentation
• Thématisation et publication pro (docs produit, API, guides…)

Parfait pour la doc d’architecture, les microservices, et la documentation produit distribuée

Les Spécifications Exécutables

• Traduction directe d’une exigence en un test automatisé
• Structuration des tests en Gherkin (Given / When / Then)
• Servent à la fois à :
  • Documenter les comportements attendus
  • Vérifier en continu leur respect
• Forme lisible par les humains : développeurs, PO, QA…

Exemple de spécification avec Spock

class CalculatriceSpec extends Specification {

  def "La somme de deux nombres – Gherkin style"() {
    given: "une calculatrice"
    def calculatrice = new Calculatrice()

    when: "je calcule la somme de #a et #b"
    def resultat = calculatrice.somme(a, b)

    then: "le résultat doit être #result"
    resultat == result

    where:
    a  | b  || result
    1  | 2  || 3
    0  | 0  || 0
    -1 | 1  || 0
  }
}

Génération automatique de documentation

• Avec un plugin Spock Reports + conversion AsciiDoc/HTML/PDF
• Exemple de sortie :

== Spécification : CalculatriceSpec

=== la somme de #a et #b doit être #result

[cols="1,1,1"]
|===
| a | b | result
| 1 | 2 | 3
| 0 | 0 | 0
| -1 | 1 | 0
|===

Exemple de site Antora multi-dépôts à partir de documentation générée

Visualisation des spécifications sur un portail de documentation :

Outils de diagrammes textuels

• Description des diagrammes en texte brut
• Stockables dans Git, versionnables, diffables
• Intégrables dans les docs AsciiDoc/Markdown
• Générables automatiquement dans les pipelines CI/CD

Exemples populaires :

• Mermaid : syntaxe simple, intégré à GitHub, Obsidian, VS Code...
• PlantUML : très expressif, idéal pour la modélisation logicielle (UML, C4…)
• Kroki : plateforme qui agrège plus de 20 moteurs de rendu de diagrammes

Exemples de syntaxe

Mermaid (diagramme d'activité)

graph TD
  A[ Anyone ] -->|Can help | B( Go to github.com/yuzutech/kroki )
  B --> C{ How to contribute? }
  C --> D[ Reporting bugs ]
  C --> E[ Sharing ideas ]
  C --> F[ Advocating ]

PlantUML (use case)

@startuml
:Utilisateur: --> (S'authentifier)
(S'authentifier) --> (Accéder aux données)
@enduml

Résultat : un diagramme lisible, versionnable, reproductible !

Le modèle C4 — Diagrammes

Source : https://c4model.com/

Exemple de C4 en plantuml

@startuml
   !include <C4/C4_Container>
   !include <tupadr3/devicons2/chrome>
   !include <tupadr3/devicons2/java>
   !include <tupadr3/devicons2/postgresql>
   LAYOUT_LEFT_RIGHT()
   Container(browser, "Browser","Firefox or Chrome", $sprite="chrome")
   Container(api_a, "API A","Spring Boot", $sprite="java")
   ContainerDb(db_a, "Database A","Postgresql", $sprite="postgresql")
   Rel(browser,api_a,"HTTPS")
   Rel_R(api_a,db_a,"pg")
@enduml

Pattern : diagrammes d'inventaire

• Regrouper les unités déployables dans des librairies réutilisables, découpées par zones fonctionnelles.
• Intégrer dans le DA (vue applicative) une big picture de l'inventaire, sans afficher les relations.

Pattern : diagrammes dynamiques

• Intégrer dans le DA (vue applicative) une big picture des principales dépendances applicatives.

Pattern : diagrammes de chaîne de liaison

• Pour chaque feature, représenter une chaîne de liaison synchrone composée d’appels successifs.

La notion de coordonnée d’architecture

• Si un DA contient des dizaines voire des centaines de diagrammes, il devient difficile de s’y référer précisément (par exemple, pour discuter d’un flux en production).
• Nous découpons les features en x chaînes de liaison synchrones de n appels.
• Exemple de coordonnées pour un flux :
  Flux numéro 5 de la chaîne numéro 3 de la feature enregistrement de la commande → timeout sur com-3:5
  ➔ Référence directe dans les tickets, post-mortems, alertes, etc.

Le Dossier d’Architecture As Code

• Basé sur du light markup (idéalement AsciiDoc)
• Diagrammes textuels intégrés (PlantUML, Mermaid…)
• Utilisation de Git et des Merge Requests pour la collaboration
• Peut être rendu et consolidé dans un site Antora
• “Développé” dans un IDE (VS Code recommandé)
• Mis à jour en continu, avec une revue annuelle complète
• Beaucoup d'admonitions (TIPS, WARNING...) : bon signe de l'utilité du DA

Le compte-rendu d’un point d’architecture

• « Commite » le point : sans CR, la réunion n’a jamais eu lieu.
• Complète les ADR et permet de justifier les décisions ou de retracer l’historique.
• Fondamental pour l’architecte : il clarifie les idées et documente les échanges.
• Une fois le CR validé, mettre à jour le DA et/ou les ADR concernés.
• À rédiger en light markup (de préférence AsciiDoc)
  ➔ et à conserver tous les CR, idéalement dans des fichiers regroupés par thème ou date, pour faciliter la recherche (ex : Ctrl+F)
• Envoyer le lien du CR par e-mail (éviter les pièces jointes)
• Accepter les corrections ou compléments via Merge Request de préférence.

Format conseillé :

1. Date
2. Liste des participant·e·s
3. Informations clés
4. Décisions prises
5. Actions à mener (formulées de façon SMART)

Les supports de présentation as code

Pourquoi présenter as code ?

• Écriture textuelle simple (Markdown, AsciiDoc)
• Versionnable avec Git
• Réutilisable et automatisable
• Indépendant des outils propriétaires (PowerPoint, Google Slides)
• Compatible avec les LLM (mise en page, émoticônes, rédaction, orthographe)
  ➔ facile à parser pour alimenter un modèle d’architecture interne
  ➔ Productivité x2

Outils Open Source populaires

La doc au plus près du code… mais où ?

• Placer la conception détaillée directement dans le dépôt Git du projet.
• Pour un petit projet mono-module, intégrer le DA dans le même dépôt que le code.
• Pour la plupart des projets, il est préférable de créer un dépôt Git dédié à la documentation, regroupant :
  • le Dossier d’Architecture (DA)
  • le suivi (comptes-rendus)
  • les ADR
  • les études techniques

Architecture As Code & Intelligence Artificielle

• Texte ? Ça vous rappelle quelque chose ? ➔ les LLM !
• Il est aujourd’hui tout à fait possible de construire un chatbot d’architecture spécifique à votre organisation.
• Objectif :
  • Fournir aux développeurs un accès rapide et ludique aux règles d’architecture
  • Réduire les malentendus, augmenter l’autonomie
  • Renforcer la transmission de savoirs implicites

Exemple d'utilisation

Pré-prompt

Tu es un assistant expert en architecture solutions qui répond UNIQUEMENT en français. 
Tu ne travaille que sur un seul projet : FOO. Tu t'appelles 'ArchBot'.
Tes réponses doivent être précises et basées sur les documents techniques fournis.
Si tu ne trouves pas d'information pertinente dans les documents, réponds simplement : 
"Je n'ai pas trouvé d'information pertinente sur ce sujet dans les documents."
Ne fais AUCUNE supposition ni invention.

Utilisation (GUI: Gradio)

3 - Les challenges de la documentation As Code

Cela reste de la documentation froide

Épouvante chez les CP ou BA face au Markdown

• Dans la plupart des cas (RETEX), il n’est pas envisageable de faire produire du light markup ou des diagrammes as code aux non-techniques.
• Blocage fréquent des non-techs face à GitLab ou GitHub.
• Notre solution : filière dédiée pour ces profils sur un wiki de type Confluence-like comme xwiki ou BookStack, avec intégration diagrams.net (ex-Draw.io).

Comment s'assurer que le DA est lu et compris ?

Bonnes pratiques appliquées chez nous :

• Livret d’accueil
  Contient les sections du DA à lire en fonction du rôle (développeur, PO, ops…).

• Quiz d’assimilation
  Environ 50 questions (30 min), suivi de 4 heures de débrief avec un architecte, un mois après l’arrivée.

• Communication proactive
  Envoi de mails ou messages à chaque évolution du DA, avec un lien direct ou un extrait ciblé.

Manque de contextualisation de certains modèles de DA

• Certains modèles d’architecture (comme le mien) sont parfois trop génériques, ce qui les rend chronophages et parfois intimidants pour leurs utilisateurs.

• Il est essentiel de filtrer les sections en fonction du contexte :

  • Par typologie d’architecture
    (ex : applicative, technique, métier)
  • Par filière technologique
    (ex : projet mobile, cloud, legacy…)

Où commence le DA et où s’arrête le guide de DEV ?

• Le guide de développement est produit et maintenu par les LeadTech et les équipes de développement.
• Le Dossier d’Architecture (DA) doit énoncer les principes directeurs de développement, sans entrer dans les détails opérationnels ou les choix d’implémentation spécifiques.

Exemple : validation des performances en DEV (DoD)

• Le DA spécifie :

  Les développeurs doivent réaliser des mini-benchmarks avec une montée en charge significative.

• Le guide DEV précise :

  Où trouver le template JMeter,
  Comment le configurer,
  Comment le lancer.

Où commence le DA et le DEX ?

• Le DEX (Dossier d'Exploitation) doit rester léger, surtout en contexte Infrastructure as Code :

  • Ne pas détailler les manifestes ou les valeurs de configuration (déjà présentes dans le code).

• Le DA se limite à décrire les principes et les technologies utilisées,
  sans mentionner les machines spécifiques ni les chronogrammes.

Exemple : gestion des sauvegardes

• Le DA spécifie :

  Une double sauvegarde de la base PostgreSQL :
  pg_dump + sauvegarde Veeam de la VM,
  Avec une politique de rétention :
  7 journalières / 5 hebdomadaires / 12 mensuelles / 2 annuelles.

• Le DEX :

  Fait référence au DA
  Décrit comment vérifier que les sauvegardes s’exécutent correctement

• Le code (ex. : CronJob Kubernetes) :

  Contient l’expression cron exacte

4 - Takeaway — Ce qu'il faut retenir

• La documentation d’architecture doit être vivante, utile, maintenue et adaptée à son audience.
• Architecture as Code = gain de traçabilité, maintenabilité, lisibilité et automatisation.
• AsciiDoc + Git + CI/CD → combo gagnant pour une doc versionnée, réutilisable et collaborative.
• Le DA donne les principes ; les guides DEV/DEX précisent les détails opérationnels.
• Modèle recommandé : DA structuré en contraintes / ENF / solutions accompagné d'ADRs.

Un projet Open Source en perspective ?

• Proposer une interface CLI et/ou un GUI et/ou un chatbot ? pour générer des templates de DA contextualisés
• Pas de base de données nécessaire : tout est stocké en texte dans un dépôt Git
• Chaque section du modèle est enrichie de métadonnées pour permettre le filtrage intelligent

{"id":"5a5f3bc5-7a1d-4f68-8385-8e1a19faf288", 
   "labels":["stockage_persistent", "niveau::avancé", "taille_projet::moyen", "taille_projet::grand"]}
# Gestion des transactions
[...]

{"id":"a1e81580-8a2d-4d4d-8f99-6c9ae9ace122", 
   "labels":["greenit", "niveau::avancé"], 
   "link_to":"51bc1362-9c2f-4cd8-81d9-face77ed4dc6"}
# Écoconception
[...]

Liens utiles

• Cette présentation :
  https://meetup-arkup-juin-2025.florat.net

• Patterns de diagrammes PlantUML / C4 (Bertrand Florat) :
  https://florat.net/architecture-as-code-with-c4-and-plantuml/

• Rédiger de bons ADR (Bertrand Florat) :
  https://florat.net/comment-faire-de-bons-adr/

• Living Documentation (Cyrille Martraire – O’Reilly) :
  https://www.oreilly.com/library/view/living-documentation-continuous/9780134689418/

Merci pour votre attention !

Des questions ? retours, suggestions ?