Forem: Arnaud Gaches

ça ressemble à quoi, mon setup Claude Code ?

Arnaud Gaches — Wed, 01 Apr 2026 17:32:51 +0000

Dans ma veille, je vois passer beaucoup de guides de setup avec 18.000 skills et 5000 hooks pour répondre à tous les besoins mais peu de REX de setup en situation réelle.
Pendant ce temps, les collègues ont vu la lumière et basculent vers Claude Code et ... se perdent dans les possibilités.
J'ai décidé de vous montrer mon setup Claude Code — c'est ce qui tient après 6 mois, et dans quel ordre je l'aurais fait si c'était à refaire.

Pendant 6 mois, j'ai configuré et joué sur plusieurs paramètres (claude.md, config MCP, settings, skills). J'ai repris plein de bonnes idées de @florian Brugniaux qu'il a stockées dans son (claude code ultimate guide.
4 organisations séparées, ~12 repos et des contextes hétérogènes entre le pro et le perso : infra Terraform, blog, 2e cerveau.

Profil archi technique, pas un profil dev — vous verrez des usages infra, editorial, veille, peu de code pur.

Table des matières

La configuration préalable du poste
Quelle configuration de Claude a été mise en place et où ?
Agent schedulé
Repo par repo
L'heure du bilan
Conclusion

1. La configuration préalable du poste

Avant de configurer quoi que ce soit, le poste a besoin d'une base.
Vos skills notamment vont réclamer plein d'outils et ... vous le découvrirez quand vous vous en servirez.

C'est un manque actuellement de ne pas avoir les prérequis à une skill et/ou un agent

Voici un extract de que qui a été installé en tools et pourquoi :

Outil	Pourquoi
`git` + `gh`	Manipuler git et GitHub depuis le terminal — remplace le MCP GitHub sans le moindre regret
`jq`	Requis par RTK
`python3` + `pip`	Claude Code génère régulièrement des scripts Python — mieux vaut l'avoir d'emblée
nvm + Node 20	Prérequis pour installer et faire tourner les MCP servers en npm/npx
agent-browser	CLI de navigation web — plus souple que Playwright CLI, moins consommateur que les MCP browser
`pandoc` + `libreoffice`	Prérequis des skills docx / pptx / pdf
RTK	Proxy token-killer : réécrit les commandes verboseuses transparentement, économies sur les tokens de sortie
Tabby	Terminal avec onglets paramétrables et split d'écrans en plus — devenu mon terminal fétiche
Extension Claude Code (VS Code)	Plugin Claude Code dans l'IDE

2. Quelle configuration de Claude a été mise en place et où ?

La configuration de Claude impose de se projeter sur l'organisation et les permissions/hooks/skills/... que l'on veut configurer et à quel niveau.
Soit en général (le settings.json et le settings.local.json de l'organisation), soit par projet.

L'anatomie du dossier `~/.claude/` global

Claude Code hérite et compose trois niveaux de configuration :

~/.claude/settings.json            → global
<org>/.claude/settings.local.json  → organisation
<projet>/CLAUDE.md                 → projet

La couche organisation reste pour l'instant vide (à travailler quand on sera en Claude Enterprise)

settings.json : déterministe vs inférentiel

settings.json est déterministe : si git push --force est dans la deny list, l'opération est physiquement impossible. Le modèle ne peut pas l'exécuter, quoi qu'il arrive.

CLAUDE.md est porté par l'inférence : l'agent lit les instructions et fait de son mieux pour les respecter.
Mais "De son mieux" n'est pas une garantie : Une règle dans CLAUDE.md peut être mal interprétée, oubliée en fin de contexte, ou contredite par une instruction conversationnelle.

Conséquence pratique : tout ce qui est critique ou irréversible va dans settings.json. Le reste va dans CLAUDE.md.

{
  "permissions": {
    "deny": [
      "Bash(git push --force*)",
      "Bash(git reset --hard*)",
      "Bash(git branch -D*)"
    ]
  }
}

Hooks globaux

La configuration des Hooks se fait aussi dans le settings.json.
Elle peut faire référence (souvent) à des scripts qu'il faut télécharger (voir doc install)

La différence avec la liste de permission : La liste de permission bloque/autorise les patterns de commandes connus à l'avance. Les hooks inspectent le contenu réel de ce qui va être exécuté.

Trois hooks en place, extraits du Claude Code Ultimate Guide :

dangerous-actions-blocker.sh — couvre les commandes destructives (rm -rf, fork bomb, DROP TABLE), le force push sur main/master, l'édition des fichiers sensibles (.env, clés SSH, credentials), et avertit sur toute suppression de fichier.

security-check.sh — bloque toute commande Bash contenant des patterns de secrets (password=, api_key=, sk-xxxxx). Deuxième couche après la blocklist git.

rtk-auto-wrapper.sh — réécrit automatiquement les commandes verboseuses (git log, git diff, cargo test...) vers leurs équivalents rtk. Transparent pour l'agent, 60-90% d'économies sur les tokens de sortie.

MCP globaux

Toujours dans le settings.json, j'avais déclaré 3 serveurs MCP — disponibles dans tous les projets sans configuration par repo.

INFO: Claude code hérite de la configuration des MCP de Claude.ia
Vous pouvez en configurer d'autres directement via la commande claude mcp add (doc) ou via le fichier settings.json
L'usage de npx dans les paramètres d'exécution du MCP permet l'installation et exécution du MCP

github — accès à l'API GitHub.
Devenu superflux en pratique : gh fait tout aussi bien depuis le terminal, et Claude Code l'utilise nativement. À retirer.

context7 — documentation à jour des librairies.
Utile ponctuellement quand on touche une stack peu familière et qu'on veut éviter les hallucinations de versions obsolètes. Usage au besoin, pas systématique.

puppeteer — browser headless Chrome.
Pratique mais remplacé depuis par le CLI agent-browser, plus souple et mieux intégré dans les workflows Claude Code. A retirer.

MCP de Claude.ai :

Slack — connecteur Slack (pour se connecter à Slack, pratique quand on a un Slack gratuit, ça permet d'extraire des infos intéressantes facilement)

Excalidraw — génération et édition de schémas visuels directement depuis Claude Code.

Mermaid Chart — production de diagrammes textuels (flowcharts, séquences, entités) intégrable en format markdown.

Skills et Plugins globales

Les skills sont des procédures configurées au global et réutilisables entre projets.

Vous pouvez télécharger des Skills existantes et les déposer dans ce répertoire pour les installer

Les plugins Skills sont des lots de skills proposés sur un marketplace et installables dans un contexte donné :

Install for you (users scope) préconisé pour plugin global
Install for all collaborators on this repository (project scope)
Install for you, in this repo only (local scope) Ils s'installent dans claude code (via la commande /plugin)

Les plugins que j'ai installés et conservés :
superpowers le plugin PowerTools de Claude Code :) link
Utilisé de manière plutôt transparente, il surperforme les actions de Claude Code :
• Commands: execute-plan, brainstorm, write-plan
• Agents: code-reviewer

document-skills
doc-coauthoring, mcp-builder, skill-creator (pour créer des skills et des MCP)
docx , pdf, pptx, xlsx (pour gérer les fichiers office, lecture, création et modifications)

Ces plugins m'ont permis de ne pas avoir besoin de créer trop de skills spécifiques et sont maintenus par Anthropic.

2 skills persos.

save-config — git add / commit / push de tout ~/.claude/ vers un repo GitHub privé. Versionner sa config Claude Code comme du code. Utile avant de modifier des hooks ou des CLAUDE.md globaux. Work in progress : il manque le restore config

document-organizer — tri et déplacement de fichiers (du dossier Téléchargements en bordel) vers leurs destinations (NAS ou local). Utilisé avec la commande /trier.

CLAUDE.md vs `/commandes` vs agents

Une nuance qui explique que j'ai aussi peu de commandes custom : il y a trois façons d'exposer des procédures à l'agent.

Les prompts dans CLAUDE.md sont contextuels — l'agent les lit et peut les appliquer selon son interprétation. Flexible, mais pas garanti.

Les /commandes réelles (fichiers dans .claude/commands/) sont des procédures fixes — l'agent les exécute telles quelles, sans interprétation. Utile pour les workflows critiques où la reproductibilité prime.

Les agents (fichiers dans .claude/agents/) sont des sous-processus avec leur propre contexte, leurs propres outils, leur propre modèle. Le pattern le plus utile : L'agent orchestre un ensemble de skills pour atteindre un objectif, chacune de ces skills effectuent une action technique précise.

Les custom commands (.claude/commands/) deviennent finalement peu utilisées en pratique — la plupart des procédures trouvent leur place dans le CLAUDE.md ou dans la déclaration d'agents qui consomment peu de tokens.

3. Agent schedulé

DevwithIA produit beaucoup de contenu — canaux actifs, threads, partages de ressources. Pas toujours le temps de tout lire.

Du coup, j'ai créé un remote trigger qui tourne chaque matin à 8h30 sur claude.ai :
En sandbox uniquement connecté aux MCP de claude.ai, l'agent lit tous les canaux, résume l'activité des dernières 24h et m'envoie un DM Slack avec le contenu des jours précédents.

Ce qui distingue ce setup d'un simple cron en local : l'agent vit entièrement dans le cloud Anthropic. Localement, j'ai conservé la configuration du trigger ID afin de le retrouver.

Une limite à connaître : ces agents ne peuvent pas faire d'appels HTTP directs vers des APIs externes. Pas de webhook custom, pas d'email via Resend. Uniquement les connecteurs MCP approuvés (Slack, GitHub...). Découvert en essayant d'envoyer un résumé par email — le proxy egress du sandbox bloque le trafic sortant vers des tiers.

Note: ce remote trigger impose d'utiliser un MCP dans claude.ai. On va le retrouver configuré pour Claude code donc pas nécessaire d'installer un plugin en plus

4. Repo par repo

Chaque folder (repo) peut aussi accueillir une configuration dédiée.
Il est recommandé de versionner ce répertoire .claude/ spécifique au projet.

3 Etapes :

créer un repository vide
git clone
dans le répertoire, claude puis /init ou copie-colle du CLAUDE.md
prompt 1 "configure le .gitignore et versionne le répertoire .claude"
prompt 2..n : "installe la skill / command / à partir de l'URL <...>"

Blog éditorial

Problème : Un repo qui a commencé comme simple espace de rédaction d'articles, et qui a grandi : récolter les idées qui me passent par la tête, créer des bases de savoir, et pouvoir générer des livrables sous formes multiples (articles, docs, REX, talks).
Maintenir une cadence LinkedIn régulière demandait des relectures systématiques — pas une fois sur deux selon la fatigue du jour.
Et chaque session recommençait à zéro : expliquer le pipeline, rappeler le ton attendu, préciser la cible.

Solution : CLAUDE.md éditorial complet (200lignes) — pipeline idée → knowledge → output, familles de contenu, guide de style avec anti-patterns IA nommés et justifiés, session start ritual avec choix de phase (idée, knowledge, output).

Deux prompts de review nommés :

Review Article : persona journaliste expérimenté.
Focus : hook (2 lignes ?), exemples concrets vs abstractions,
ton (praticien vs promotionnel), comptage vs cible LinkedIn, qualité du CTA.

Review Lecteur : lecteur saturé du contenu IA générique.
Scoring /10 sur 4 axes : rigueur argumentaire, qualité sources,
professionnalisme du ton, précision des données.

Le scoring /10 reste aussi pratique pour mesurer la progression (ou récession).

le setup étant gros, contactez-moi si vous voulez le contenu

Lab Scaleway / infra

Problème : Un lab infra en cours, avec deux besoins parallèles : écrire un REX publiable ET conserver une doc technique précise des choix, des décisions, des problèmes rencontrés. Et pour être probant — montrer que l'IA a vraiment été utilisée sur un projet réel — il fallait des traces : durée des sessions, nombre d'itérations, complexité des opérations. Sans ça, "j'ai fait ça avec Claude Code" reste invérifiable.

Solution : Hooks PostToolUse et SessionEnd qui journalisent chaque appel d'outil dans des fichiers Markdown horodatés. Commande Bash exécutée, fichier écrit, fichier édité — tout est loggué dans un sous-répertoire du repo ia-logs/.
Cela apporte une observabilité native des sessions sur un repo où les erreurs ont des conséquences réelles.

Deux personas de review dans le CLAUDE.md : un ingénieur senior et un speaker de conférence — pour relire la doc technique avec deux angles différents.

Thinking — le 2e brain perso

Problème : Des projets personnels sans code — refonte de CV, tri de 15 ans de photos sur un NAS et deux comptes Onedrive, recherche d'une maison.
Des sujets hétérogènes, des besoins ponctuels, chacun avec son contexte propre à ne pas réexpliquer à chaque session.

Solution : Un répertoire thinking/ structuré comme un 2e cerveau, avec un CLAUDE.md par domaine. Le principe est le même que pour les repos code : poser la problématique une fois, travailler en équipe avec l'IA, développer des stratégies adaptées au besoin.

thinking/jobs/ — refonte du CV et analyse d'adéquation CV/annonce. Le CLAUDE.md contient un persona /headhunter complet : chasseur de tête IT senior, formulations types, cas d'usage. Plutôt que d'expliquer le rôle attendu à chaque fois, il est encodé une fois et activé à la demande.

thinking/IT/ — au départ pour les sujets IT, il a porté surtout un sujet de tri de photos NAS + OneDrive sur deux comptes sans perte. Les règles métier sont dans le CLAUDE.md : déplacer vers _trash/ plutôt que supprimer, scripts idempotents, chemins via variables d'environnement.
Et surtout, Claude ne fait que fournir les commandes, c'est moi qui les exécute.

thinking/maison/ — plusieurs sujets immobiliers : scraping d'annonces, comparaison de biens, stratégies de recherche. Le CLAUDE.md conserve le contexte après la fin d'un projet — mémoire de ce qui a été fait, pour ne pas repartir de zéro si le sujet reprend. Faire une liste excel à partir des pdf des différentes annonces (merci les skills pdf et xlsx :)

thinking/orga/ — ici, un truc tout bête : reposer l'organisation de la semaine pour en créer des évènements à rajouter dans un agenda Google. Du one-shot pour générer des fichiers .ics avec la récurrence nécessaire pour Google Agenda.

thinking/voiture/ — Calcul de TCO global et comparatif de scénarios entre thermique, EV, hybride. Donc recherche sur Internet sur les différents modèles avec consommation, prix, moteur, et création d'un xlsx de comparaison.

5. L'heure du bilan

Ce qui fonctionne bien

Le digest Slack automatisé chaque matin est appréciable pour repérer ce que je ne dois pas rater dans le slack.
Les "skills" de review restent pour moi utiles pour leurs retours et critiques, même si c'est facile de craquer avec ces avis qui deviennent parfois contraires entre les sessions.
Les sessions du lab génèrent bien des logs de sessions de manière automatique.

Et ces skills docx/pptx sont une super découverte : Elles vous permettent de travailler en markdown versionné puis de de créer rapidement et sans trop d'efforts un doc/ppt Office.

Enfin, le 2e cerveau, c'est peut-être ce qui m'impacte le plus sans que je réalise vraiment :
Entre ce thinking/ pour les projets perso et le blog pour les idées tech, ma charge mentale s'est allégée.

Moins de Post-it mentaux à garder en tête et plus d'espace pour penser.
(mais du coup, hop une nouvelle idée, vite, claude, mon dieu cela ne s'arrêtera pas)

Ce qui m'irrite encore

L'aide à la rédaction de l'IA ramène toujours aux mêmes éléments de ton et de style rédactionnel. Et ce style "formaté IA", c'est insupportable pour moi.
Vraiment, sur un petit bout de texte, c'est bien. Mais lui demander de réécrire un article, ça peut virer au cauchemar.

En plus, les skills d'amélioration rajoutent beaucoup de verbose dans les fichiers de configuration. Donc si à chaque erreur, Claude décide de rajouter une règle, ça empile et ça empire. A force, je trouve que cela dégrade les performances des réponses.

Enfin, je n'ai pas encore trouvé comment partager entre 2 ordinateurs un repo commun avec une configuration de Claude code globale (le blog sur lequel je travaille aussi sur mon temps perso). Je perds systématiquement la memory qui est stockée dans le ~/.claude et pas dans le projet.
Vous avez vu la skill save-config qui tente déjà de sauvegarder, reste à restaurer maintenant :)
En environnement d'entreprise, je partirais sur des solutions plus robustes comme Packmind par exemple.

Ce qui manque encore

Je ne systématise pas encore le Plan Mode (/plan, lecture seule avant toute opération lourde).
Alors que pourtant j'applique un process "spec->plan->ask".
Je lui demande de "planifier avant d'agir" mais ça reste une instruction, pas une contrainte technique.
/plan rend l'agent physiquement incapable d'écrire pendant la phase d'exploration. Ce ne sont pas deux façons équivalentes de faire la même chose.

Les rules/ (fichiers d'instructions modulaires, réutilisables entre projets) ne sont pas encore utilisées. Je ne vois pas encore comment elles peuvent fonctionner et ce qu'elles peuvent apporter.

6. Conclusion

Voici un point d'entrée concret (setup et usage) :
De quoi voir par vous-même si les enthousiastes de l'IA ont raison — ou pas.

Et vous, au fait, vous avez quoi comme setup Claude Code ?

Vous avez raté la vague MCP ? C'est pas grave.

Arnaud Gaches — Fri, 20 Mar 2026 12:08:53 +0000

partage tentant de résumer les propos et donc mentionnant des personnes de la communauté Dev with IA (https://www.devw.ai/). Pour des raisons de publications, les noms de familles ont été enlevés.

Trois actes, trois interfaces

Les interfaces IA ont évolué vite. Très vite.

2022-2023 : le browser. ChatGPT, Claude, Gemini. L'IA dans un onglet. Puissante en génération, mais coupée de votre environnement de travail. Aucune interaction avec les fichiers, les outils, les systèmes.

2024-2025 : l'IDE + MCP. Les IA entrent dans l'IDE : Copilot, Cursor, Continue.dev. Mais l'IDE est un silo. Pour en sortir, Anthropic lance le Model Context Protocol fin 2024 : un standard ouvert pour connecter les agents aux APIs, bases de données, GitHub, Slack — via une interface typée. OpenAI l'adopte officiellement. En décembre 2025, Anthropic cède MCP à la Linux Foundation. L'écosystème explose.

2025-2026 : les agents CLI. Claude Code, Kilocode, OpenCode, Gemini CLI, GitHub Copilot CLI, Codex CLI. Tous les acteurs majeurs ont maintenant un agent terminal. L'IA ne se contente plus de lire et répondre — elle exécute des commandes, lit et écrit des fichiers, appelle des APIs. Sans couche intermédiaire. Et de manière déterministe.

En plus les outils gh, kubectl, psql, aws que vous avez déjà sont immédiatement utilisables par l'agent.

L'argument n°1

L'argument principal du CLI-first, c'était le coût token : chaque serveur MCP injectait des centaines de tokens dans le contexte avant la première commande utile. Connectez 5 serveurs, et 15-20% de votre fenêtre de contexte est consommée avant d'avoir fait quoi que ce soit.

Sauf que.
Antoine l'a repéré il y a quelques jours : Les dernières mises à jours des outils (claude code) font les MCP non utilisés dans la session courante injectent désormais 0 tokens. Vérifiable avec un /context dans une session quasi vierge. L'argument n°1 du CLI-first vient de tomber.

Le coût contexte reste réel pour les serveurs activement sollicités — mais la pénalité "à blanc" a disparu.

Le choix dépend du modèle

C'était un angle manquant dans les articles comparatifs alors qu'il est pourtant très structurant.

Antoine encore : "Claude Opus/Sonnet 4.6 sont assez forts pour driver une CLI (ex: aws-cli) → le MCP (ex: aws-labs) est superflu. Un Qwen 3.5-30b local sera bien moins agile à driver aws-cli. Le MCP d'aws-labs sera alors bien plus adapté."

Dit autrement : un frontier model — les gros modèles comme Claude Opus, Sonnet 4.6, GPT-4o — sait lire un --help, comprendre les flags, enchaîner les commandes shell sans aide structurée. Le MCP ne lui apporte rien. A l'inverse, un modèle plus petit, typiquement ceux qu'on fait tourner en local (Qwen, Llama, Mistral), a besoin de l'interface structurée du MCP comme guide. Les descriptions typées des outils, les schémas de paramètres — c'est exactement ce qui aide un modèle moins capable à s'y retrouver.

Le choix MCP vs CLI n'est pas une question de préférence mais une question de capacité du modèle qui l'utilise.

L'heuristique du terrain

Joan a une règle simple : "Je préfère CLI pour les actions déterministes. Pour GitLab, j'utilise glab CLI encapsulé dans un CLI maison. Utilisable par les humains ET par l'IA. Pareil pour Slack. Pas encore fait pour Jira où j'utilise MCP."

Déterministe, répétable, bien documenté → CLI.
Exploratoire, mal structuré, API inconnue → MCP.

Et Maxime ajoute un avantage concret : "Un CLI + skill dans ~/.agents/skills/, c'est dispo pour tous tes projets et tous les agents. Pas besoin de configurer le MCP partout." La portabilité cross-projet, un argument qu'on sous-estime.

L'industrialisation : pas si simple

Arnaud a résumé le piège en une phrase : "Je voulais faire un truc comme mcp2cli mais ça me faisait bizarre d'avoir API → MCP → CLI, c'est un peu contre-productif."

Le bon chemin, c'est API → CLI directement. Construire une bonne CLI sur des APIs solides, c'est un investissement qui sert à tout le monde — humains, scripts CI/CD, et agents IA. Passer par MCP pour ensuite re-wrapper en CLI, c'est ajouter une couche d'indirection sans valeur.

Une piste à surveiller si l'outil n'a pas de CLI : CLI-Anything permet de générer automatiquement une CLI depuis le code source d'un logiciel (open source évidemment). L'approche est intéressante et pose la question de l'effort de créer un MCP vs CLI quand vous avez les sources de votre outil.

L'argument enterprise

Thomas travaille avec une équipe sur l'industrialisation des accès MCP remote. Deux arguments forts que la CLI ne couvre pas :

Le maintien à jour centralisé. Distribuer et maintenir des CLIs sur les postes de chaque dev, c'est la galère. Même avec brew ou scoop. L'intérêt d'un MCP serveur remote, c'est un seul point de mise à jour.

L'observabilité des usages. Un enjeu pour les DSI et responsables qui investissent dans l'outillage IA. En CLI sur le poste du dev, c'est capot — ou trop complexe à instrumenter. Avec un MCP serveur remote, l'observabilité devient native.

Ces arguments restent importants pour l'entreprise qui déploie des agents à l'échelle.

Ce débat ne se pose que quand on a le choix

Et c'est peut-être le point le plus important.

MCP vs CLI, c'est un arbitrage qui n'existe que dans un contexte où on a le choix — concrètement, un dev avec un terminal et la maîtrise de son environnement.

Un agent-as-a-service, une plateforme interne, un utilisateur non-tech qui veut juste connecter Slack ou GitHub à son assistant — aucun des ces cas n'utilisera une CLI.

Prenez Cowork (Anthropic) : les connecteurs sont des MCP. Vous avez certes des outils CLI, mais embarqués dans la VM, mais transparents pour l'utilisateur. C'est la skill qui installe les tools nécessaires, rendus invisibles à l'utilisateur.

Cédric : "Même en interne, on a mis de côté des use cases MCP au profit de skills+CLI."
Damien : "Une bonne pratique est d'utiliser des CLI plutôt que les MCP quand tu as l'opportunité. Ça consomme beaucoup moins de tokens et c'est souvent plus efficace."

Mais "quand tu as l'opportunité" est la clé de la phrase. Beaucoup de contextes ne l'offrent pas.

Les deux vont coexister. Et c'est normal.

La vraie question

Le débat MCP vs CLI est secondaire. Ce qui compte, c'est ce qu'il y a en dessous : la qualité du contrat API. Une API bien conçue — stable, documentée, prévisible — se consomme en CLI, en MCP, ou directement par un agent. Une API bancale restera bancale quelle que soit la couche d'abstraction au-dessus.

Pour le reste, la stratégie dépend de plusieurs facteurs concrets : ce qui existe déjà dans votre stack (une bonne CLI disponible ? un MCP communautaire maintenu ?), la capacité du modèle que vous utilisez (frontier ou local ?), le contexte de déploiement (dev solo ou plateforme distribuée ?), et honnêtement — ce sur quoi votre équipe est à l'aise. Un MCP que personne ne sait déboguer, c'est pire qu'une CLI rustique bien maîtrisée.

Construisez de bonnes APIs. L'IA s'en servira — en CLI ou en MCP. Et vous aussi.

Vous aussi vous avez basculé 100% CLI ? Et surtout — est-ce que vous avez vraiment eu le choix ?

IA #DevTools #CLI #MCP #AgentsIA #PlatformEngineering

OpenAI a perdu 22 points en 12 mois : Le marché IA se recompose.

Arnaud Gaches — Thu, 19 Feb 2026 14:49:35 +0000

Il y a 12 mois, ChatGPT représentait 87% du marché de l'IA conversationnelle. Aujourd'hui : 64%. Pendant ce temps, Copilot de Microsoft — malgré 13 milliards investis et une touche dédiée sur votre clavier — stagne à 1.1%. Comment on en est arrivé là et comment ça va finir ?

1. OpenAI : l'érosion pas si silencieuse

Les chiffres parlent d'eux-mêmes :

Période	ChatGPT	Gemini	DeepSeek	Grok	Perplexity	Claude	Copilot
Jan 2025	86.7%	5.7%	–	–	1.9%	1.5%	1.5%
Juil 2025	78.6%	8.6%	4.8%	2.1%	1.6%	1.5%	1.1%
Oct 2025	74.1%	12.9%	3.7%	2.0%	2.4%	2.0%	1.2%
Dec 2025	68.0%	18.2%	3.9%	2.9%	2.1%	2.0%	1.2%
Jan 2026	64.5%	21.5%	3.7%	3.4%	2.0%	2.0%	1.1%

Source : SimilarWeb Global AI Tracker [1], trafic web mensuel. Exclut apps mobiles, clients desktop et intégrations embarquées — les parts réelles de Copilot et Gemini sont probablement supérieures. Couverture : Fortune [2], SEJ [3].

-22 points en 12 mois.

Un rythme constant de 5 à 6 points par trimestre.

Si le rythme se maintient (ce qui suppose qu'aucun effet plancher ne freine l'érosion) ChatGPT passerait sous les 50% avant fin 2026. Et les utilisateurs ne partent pas chez Copilot comme on aurait pu le penser vu le partenariat historique Microsoft-OpenAI.

Où vont les utilisateurs ?

Chez Google. Gemini a quadruplé en 12 mois. Le reste — DeepSeek, Grok, Perplexity, Claude — progresse lentement mais semble s'installer durablement.

Et derrière l'érosion, un problème de modèle économique.

900 millions d'utilisateurs hebdomadaires en janvier 2026 [4] — impressionnant.

Combien paient pour le service ? Environ 20 à 35 millions d'abonnés [5], soit moins de 5% de la base. L'immense majorité utilise ChatGPT gratuitement. L'introduction de publicités en février 2026 [6] (réservées aux utilisateurs gratuits et "Go") confirme le diagnostic :

OpenAI vise 1 milliard de revenus publicitaires en 2026 [7], 25 milliards d'ici 2029.

Quand vous ajoutez des pubs, c'est que les abonnements ne suffisent pas.

Et le poste de coût est colossal :

OpenAI ne possède pas d'infrastructure en propre. Ils dépensent 8.7 milliards en inférence Azure rien que sur les trois premiers trimestres 2025 [8], un backlog de 281 milliards de revenus engagés envers Microsoft dont 250 milliards ajoutés par le nouveau contrat d'octobre 2025 [9]. Rajoutez enfin l'IA générative — Sora, DALL-E, génération vidéo — qui consomme des ressources de calcul bien supérieures au texte.

Résultat : 14 milliards de pertes projetées en 2026 [10] et une rentabilité espérée... pas avant 2030 [11].

Un analyste estime qu'OpenAI pourrait être à court de cash dès mi-2027 sans nouvelle levée [12].

En bref, OpenAI brûle beaucoup trop de cash, sans infrastructure en propre, perd des parts, et voit son partenaire historique Microsoft se tourner vers la concurrence. Les controverses de gouvernance — dissolution de l'équipe de sécurité IA [55], départs en cascade, et le rapport "OpenAI Files" documentant les promesses brisées [56] — n'aident pas à inverser la tendance.

2. Copilot, un parfum de Windows Me

Note : Copilot ne doit pas être confondu avec GitHub Copilot, l'outil d'assistance au code — qui lui rencontre un beau succès : 20 millions d'utilisateurs [27], 42% du marché du code assist IA [28], 90% du Fortune 100.

C'est peut-être le chiffre le plus mauvais du tableau : 1.1%.
Microsoft a pourtant énormément dépensé :

13 milliards USD engagés dans OpenAI, dont 11.6 effectivement versés : un investissement qui a coûté 3.1 milliards de perte nette à Microsoft [14].

Intégration dans Windows 11, Edge, Office 365, Teams.

Touche physique sur les claviers [15], une première depuis 30 ans, depuis la touche Windows en 1994. Lenovo, Dell, HP, Asus, Samsung ont embarqué [16].

Résultat : 1.5% → 1.1% en 12 mois.
Ça baisse.
Après un pic mi-2025 (+19% de trafic en septembre), Copilot s'est effondré en décembre (-19%).

Comme si les gens avaient essayé... et n'avaient pas été convaincus.

Pendant ce temps, Grok — sans intégration système, sans touche dédiée — a ajouté en un mois presque la moitié de la part totale de Copilot.

Le silence de Microsoft est éloquent.

Aucun chiffre d'adoption publié pour Windows 11. Pourtant, Copilot affiche 71 000+ avis sur le Microsoft Store (contre 2 000 pour ChatGPT) — ça reflète quelque chose de significatif.
Comme le note WindowsLatest [17] : "If Copilot were popular on Windows 11, Microsoft would have bragged about it."

Le parallèle avec Windows Me n'est pas gratuit.
Un produit poussé sur le marché pour combler un trou dans la gamme, que tout le monde a contourné en attendant mieux (#1 pire produit Microsoft et #4 des pires produits tech de l'histoire selon PCWorld [19]).

Copilot dans Windows 11, c'est la même logique : un produit forcé dans un écosystème que les utilisateurs ignorent ou désactivent.

Et l'écosystème en question n'est pas en grande forme non plus. Windows 11 lui-même peine à convaincre : après avoir brièvement dépassé Windows 10 mi-2025, sa part a reculé de 55% à 50.7% en deux mois [20] [21].
L'IA omniprésente y est pour beaucoup : Copilot injecté dans Notepad, Paint, l'Explorateur de fichiers, la barre des tâches — au point que des outils de "debloat" comme Winslop [22] ont émergé pour purger les fonctionnalités IA.

En janvier 2026, Microsoft a fini par admettre que Windows 11 "avait déraillé" et promis de réduire les intégrations Copilot [23].

Les utilisateurs préfèrent migrer de Windows 10 vers ... Linux. 11% de parts de marché en France [25], 4.7% au niveau mondial [26].

Quand vos utilisateurs préfèrent changer d'OS plutôt que d'accepter votre IA, le message est tout aussi clair.

Le signal le plus révélateur vient de l'intérieur.
En février 2026, Microsoft a ouvert ses équipes à tous les outils IA du marché — Claude Code, Cursor, et autres — en leur demandant de comparer.
Résultat : les ingénieurs Microsoft ont plébiscité Claude Code [24].

Quand les propres équipes de Microsoft préfèrent la concurrence, c'est un signal difficile à ignorer.

Copilot cumule tout ce qui peut mal tourner : un produit imposé dans un OS qui perd lui-même du terrain, un investissement de 13 milliards pour 1.1% de part de marché, et des équipes internes qui préfèrent la concurrence. En bref, le Windows Me de l'IA.

3. Mon pari : le marché IA de 2027 en 4 piliers

Les chiffres de janvier 2026 ne montrent pas juste un déclin d'OpenAI. Pour moi, ils montrent la restructuration d'un marché autour de quatre modèles économiques distincts.

Pilier 1 — Google/Gemini : le généraliste dominant

De 5.7% à 21.5% en 12 mois. La trajectoire est claire.

Google n'a même pas besoin d'avoir le meilleur modèle. Il lui suffit d'être assez bon et présent partout. 3 smartphones sur 4 tournent sous Android. 2 navigateurs sur 3 sont Chrome. 9 recherches sur 10 passent par Google.

Gemini s'injecte progressivement dans tout : il remplace Google Assistant sur Android, apparaît dans Search via AI Overviews (100+ pays), et s'intègre dans Gmail, Docs et Sheets. Résultat : 650 millions d'utilisateurs actifs mensuels en octobre 2025, +44% en trois mois (SimilarWeb).

Ajoutez l'infrastructure de datacenters avec processeurs dédiés TPU déjà installés et les compétences accumulées depuis 2014 via DeepMind. Là où OpenAI brûle 8.7 milliards par an en location d'infrastructure Azure, Google fait tourner ses modèles sur ses propres puces, dans ses propres datacenters — un avantage structurel de coût sur ses concurrents (Azure et AWS tentent d'ailleurs de rattraper le retard à marche forcée).

Google avait raté le démarrage de la vague LLM. Mais à horizon 2027, Gemini paraît être le favori naturel sur le grand public — et un argument supplémentaire pour aller vers l'écosystème Google.
Et 2e effet : en intégrant l'IA directement dans Search via AI Overviews, Google protège son moteur de recherche plutôt que de se faire cannibaliser par les chatbots concurrents — une position qui devient défensive sur son coeur de business en plus d'offensive sur l'IA.

C'est d'ailleurs ce qui rend pour moi Google si pertinent dans cette course : contrairement à OpenAI et Anthropic qui doivent créer un modèle économique rentable de zéro, Google a surtout à défendre un business existant à 300 milliards de revenus publicitaires tout en y greffant l'IA.

Pilier 2 — Anthropic/Claude : le premium pour les pros

2% de part de marché web. Ça paraît dérisoire. Mais qui sont ces 2% ?

Anthropic n'a pas vraiment cherché le grand public. Le positionnement est délibérément "de niche" : assistance au code, usage professionnel, tâches complexes. Pas de campagne marketing massive, pas d'intégration forcée dans un OS; limitations des usages gratuits.

Le revenu vient des API B2B et des abonnements pro — ce qui explique le décalage entre la part de marché visible et les chiffres financiers.

Et pourtant : 14 milliards USD d'ARR début 2026 [29], dont une part majoritaire via les API B2B — et 2.5 milliards pour Claude Code seul (chiffre presse, non confirmé officiellement). Valorisation : 380 milliards USD (Series G, février 2026) [29].

Projection 2028 : 70 milliards de revenus [31].

La réputation s'est construite sur la qualité des modèles — Claude Sonnet 4.5 fait régulièrement partie du top des classements développeurs (LMSYS Chatbot Arena [32]) — puis sur Claude Code, qui a capté une audience pro prête à payer. Jusqu'à convaincre les ingénieurs de Microsoft eux-mêmes (cf. section Copilot) — le marketing d'Anthropic les remercie de cette pub gratuite.

Le contraste avec OpenAI est saisissant quand on regarde le revenu par utilisateur.
OpenAI génère environ 20 milliards d'ARR avec 900 millions d'utilisateurs — soit ~22$ par utilisateur et par an [33] [4].

Anthropic génère 14 milliards d'ARR avec 30 millions d'utilisateurs actifs — soit ~467$ par utilisateur et par an [34] [35].

Un ratio de 1 à 21 — indicateur de mix produit (B2B API vs grand public) autant que de valeur perçue.
C'est ce qui pourrait permettre à Anthropic d'atteindre un équilibre financier bien avant OpenAI et ses 14 milliards de pertes annuelles [10].

En contrepartie : Anthropic ne possède pas d'infrastructure en propre et dépend d'hébergeurs tiers pour ses capacités de calcul. Un point de fragilité à surveiller.

Un peu comme Notion face à Google Docs — moins d'utilisateurs, mais ceux qui restent paient, et beaucoup.

En toute transparence : j'utilise Claude (code) au quotidien. J'ai essayé d'argumenter au maximum mes positions sur ce positionnement "premium pro". À vous de juger si un biais est présent.

Pilier 3 — L'IA locale

Ce pilier n'apparaît dans aucune statistique de trafic web. Et c'est justement ce qui le rend intéressant.

Côté logiciel, les poids lourds (Meta, Google, Microsoft, Mistral) publient des modèles ouverts. Des outils comme Ollama (115k+ stars GitHub) [36] et LM Studio (10M+ téléchargements) rendent l'utilisation triviale.

Côté hardware, ça tourne déjà :

Un Mac Mini M4 Pro à 1 400€ fait tourner un modèle 32B en 4-bit à ~14 tokens/s [49] — environ 10 mots par seconde
Un cluster de 8 Mac Mini avec Exo [50] a fait tourner DeepSeek V3 — 671 milliards de paramètres [51]
Côté mobile, PocketPal [53] fait tourner des modèles 3-4B sur smartphone sans connexion, et un iPhone 17 Pro a atteint 136 tokens/s — environ 95 mots par seconde — sur un petit modèle optimisé INT8 [54]

Les cas d'usage sont concrets : rédaction, résumé de documents, recherche documentaire — le tout en confidentialité totale, hors-ligne, sans abonnement.
Après, j'ai eu beau chercher : on manque encore de données sur l'usage réel au quotidien. Des stars GitHub et des téléchargements donnent une vision de l'adoption d'outils, pas de son usage réel.

La limite reste la puissance : pour les tâches complexes (raisonnement, code, agents), les modèles 30B+ restent nécessaires et ne tournent pas sur un laptop standard. Les hébergeurs (Scaleway, Google, Azure) permettent de faire tourner des modèles ouverts sur infrastructure dédiée — un compromis entre souveraineté et puissance de calcul.

Mais la trajectoire est claire — dans deux ans, un laptop ou un smartphone standard devrait suffire pour les tâches courantes.

Apple est très bien positionné sur ce créneau. Ses puces M* sont déjà parmi les meilleures pour l'inférence locale — Apple publie de la recherche sur l'exécution de LLM avec le M5 [37], et le M5 Ultra attendu mi-2026 promet 80 coeurs GPU.
Et Apple a signé un partenariat sur plusieurs années avec Google en janvier 2026 [38] : Apple peut se servir de Gemini pour ses solutions d'IA (qui a dit Gemini en local sur un Mac ?).

Apple n'est pas le seul : AMD pousse ses Ryzen AI, Qualcomm ses Snapdragon X — tous les fondeurs investissent massivement dans l'inférence locale. La course au "LLM on device" est lancée.

Pilier 4 — L'inconnue chinoise

Un facteur que les stats "mondiales" ne remontent pas : la progression de la technologie chinoise.

Le marché IA chinois est déjà énorme — on ne le voit juste pas
Le Great Firewall cloisonne dans les deux sens : ChatGPT, Claude et Gemini sont inaccessibles en Chine, et les acteurs chinois n'apparaissent pas dans les stats SimilarWeb.
Alibaba (Qwen), Baidu (Ernie), Tencent (Yuanbao), DeepSeek (DeepSeek), ByteDance (Doubao), Moonshot (Kimi) se sont livrés une guerre féroce de conquêtes d'utilisateurs pour le nouvel an lunaire [39].
Résultat : une course à l'innovation (et aux cadeaux) intense, plutôt invisible depuis l'Occident.

Seedance 2.0, le dernier modèle d'IA générative de vidéos a fait parler de lui à Hollywood avec une scène d'action entre Tom Cruise et Brad Pitt des plus réaliste 39-1 39-2.

DeepSeek a déjà prouvé qu'un acteur chinois peut créer un séisme mondial
N°1 de l'App Store iOS US en janvier 2025, 600 milliards de capitalisation Nvidia évaporés en une séance [40], 125 millions d'utilisateurs mensuels en mai 2025 [41]. Sa part hors Chine s'est stabilisée à 3.7%, limitée par les préoccupations de sécurité (données hébergées en Chine) et les contraintes réglementaires des deux côtés.

Et ce n'est pas que du logiciel.
Au CES 2026, 21 des 38 exposants en robotique humanoïde étaient chinois [42].
AgiBot (chinois) est devenu le premier expéditeur mondial de robots humanoïdes avec ~5 000 unités en 2025 [43].

La technologie d'IA chinoise pourrait bien arriver par la robotique — un domaine où ils sont déjà très forts.

On a déjà vu ce scénario.

Xiaomi est n°3 mondial en smartphones.
DJI tient 70% du marché mondial des drones [44].
Dreame et Roborock dominent les robots aspirateurs pendant qu'iRobot — l'inventeur du robot aspirateur — a été revendu [45].
Huawei reste incontournable en infrastructure réseau malgré les sanctions.

Le schéma est toujours le même : rapport qualité-prix agressif, domination du volume domestique, investissement R&D massif, puis expansion internationale.

Tous ces produits vont intégrer à terme des fonctionnalités IA, basées sur des moteurs d'IA chinois.

Les solutions chinoises (DeepSeek ou Kimi) [46] sont ce 4e pilier qui va être tiré avec l'adoption de la robotique chinoise.
Mais je manque encore de recul pour pouvoir estimer quand cela va arriver. Je parierais "dans les 5 ans au plus tard".

L'histoire récente montre que face à la qualité et au prix de la tech chinoise, les réticences disparaissent de plus en plus chez les acheteurs européens.

Que deviennent les autres sociétés d'IA ?

Mistral (~0.1%) : IA française avec des modèles compétitifs, 14 milliards de valorisation [47] et une croissance de trafic de +420% — mais quasi invisible hors de France en trafic web.
Perplexity (2%) : niche sur la recherche augmentée, positionnement clair mais qui ne semble pas avoir le potentiel de croître au-delà de ses 2%.
Grok (3.4%) : captif de l'écosystème X/Twitter, croissance dépendante de Musk et de sa base d'utilisateurs.

Ces acteurs partagent deux limites communes :

Leur portée est contrainte par leur écosystème d'origine dans lequel ils sont intégrés.
Ils n'ont pas la capacité financière des autres acteurs pour s'exposer plus.

Mistral, par exemple, a signé un contrat avec le Ministère des armées français [48].

Pour survivre, ils devront se tailler un marché de niche rentable — avec une croissance plus faible mais stable. Un modèle à la Basecamp plutôt qu'en mode licorne.

Un marché de niche est déjà en train de se structurer : les IDE augmentés par l'IA : Cursor, Windsurf, GitHub Copilot code...

Le pari est d'autant plus facile que le marché des IDE payants existe déjà — JetBrains (IntelliJ, WebStorm, Rider) facture ses abonnements depuis des années.

Passer d'un abonnement JetBrains à un abonnement Cursor, c'est un upgrade naturel, pas un changement de paradigme.

4. Et donc, on fait quoi ?

Il n'y aura pas de monopole. Le marché IA se structure autour :

d'offres cloud matures avec Google et Anthropic en tête,

d'une IA locale qui se démocratise à grande vitesse,

des produits chinois en embuscade — intégrés dans les produits du quotidien ou utilisés directement.

OpenAI reste premier en parts de marché, mais a perdu l'initiative : ce sont les autres qui dictent le rythme désormais.

Si vous êtes utilisateur d'IA, trois recommandations :

Ne pariez pas sur un seul cheval.
Les chiffres de ChatGPT il y a 12 mois semblaient intouchables. Si vous êtes sur un seul fournisseur, prévoyez un plan de backup.
Si usage par API, mettez une couche d'abstraction devant votre moteur d'IA.
Utilisez un wrapper multi-provider (comme OpenRouter ou LiteLLM).
C'est de toute façon une bonne pratique pour gérer proprement les appels aux moteurs d'IA.
Si abonnement, visez des outils multi-modèles.
GitHub Copilot, Cursor et Continue.dev permettent déjà de basculer entre ChatGPT, Claude et Gemini.

C'est d'ailleurs la limite actuelle de Claude Code, verrouillé sur les modèles Anthropic — ce qui explique la multiplication des alternatives pour le connecter à d'autres providers.

Et vous, êtes-vous prêts à la descente d'OpenAI ?

IA #OpenAI #Microsoft #Copilot #Google #Anthropic #Strategie #Dev

Mes sources

[1] SimilarWeb Global AI Tracker — https://x.com/Similarweb/status/2008805674893939041
[2] Fortune — https://fortune.com/2026/02/05/chatgpt-openai-market-share-app-slip-google-rivals-close-the-gap/
[3] Search Engine Journal — https://www.searchenginejournal.com/google-gemini-gains-share-as-chatgpt-declines-in-similarweb-data/564690/
[4] Incremys, Statistiques ChatGPT — https://www.incremys.com/ressources/blog/statistiques-chatgpt
[5] Business of Apps, ChatGPT Statistics — https://www.businessofapps.com/data/chatgpt-statistics/
[6] OpenAI, approche publicitaire — https://openai.com/index/our-approach-to-advertising-and-expanding-access/
[7] CNBC, OpenAI ads — https://www.cnbc.com/2026/01/16/open-ai-chatgpt-ads-us.html
[8] TechCrunch, coûts Azure OpenAI — https://techcrunch.com/2025/11/14/leaked-documents-shed-light-into-how-much-openai-pays-microsoft/
[9] Next Platform, dépendance Microsoft-OpenAI — https://www.nextplatform.com/2026/01/29/microsoft-is-more-dependent-on-openai-than-the-converse/
[10] Yahoo Finance, pertes OpenAI — https://finance.yahoo.com/news/openais-own-forecast-predicts-14-150445813.html
[11] Fortune, rentabilité OpenAI 2030 — https://fortune.com/2025/11/12/openai-cash-burn-rate-annual-losses-2028-profitable-2030-financial-documents/
[12] Tom's Hardware, cash runway OpenAI — https://www.tomshardware.com/tech-industry/big-tech/openai-could-reportedly-run-out-of-cash-by-mid-2027-nyt-analyst-paints-grim-picture-after-examining-companys-finances
[14] CNBC, perte nette investissement Microsoft — https://www.cnbc.com/2025/10/29/microsoft-open-ai-investment-earnings.html
[15] Microsoft Blog, touche Copilot — https://blogs.windows.com/windowsexperience/2024/01/04/introducing-a-new-copilot-key-to-kick-off-the-year-of-ai-powered-windows-pcs/
[16] The Verge, touche Copilot constructeurs — https://www.theverge.com/2024/1/4/24023809/microsoft-copilot-key-keyboard-windows-laptops-pcs
[17] WindowsLatest, Copilot market share — https://www.windowslatest.com/2026/01/09/is-microsoft-losing-the-ai-race-copilot-web-is-still-stuck-at-1-market-share-we-dont-know-how-popular-it-is-on-windows-11/
[19] PCWorld, worst products ever — https://www.pcworld.com/article/535838/worst_products_ever.html
[20] The Register, Windows 11 StatCounter — https://www.theregister.com/2025/12/03/windows_11_statcounter/
[21] Windows Central, retour à Windows 10 — https://www.windowscentral.com/microsoft/windows-11/windows-11s-growth-has-officially-hit-a-brick-wall-and-users-appear-to-be-fleeing-back-to-windows-10
[22] XDA Developers, Winslop — https://www.xda-developers.com/tired-of-copilot-winslop-lets-you-easily-purge-windows-11-ai-features/
[23] WindowsLatest, Windows 11 "off track" — https://www.windowslatest.com/2026/01/31/microsoft-reportedly-admits-windows-11-went-off-track-cuts-back-copilot-and-promises-real-fixes-in-2026/
[24] Clubic, ingénieurs Microsoft et Claude Code — https://www.clubic.com/actualite-596728-c-est-le-comble-pour-microsoft-qui-fait-adopter-claude-code-a-ses-equipes-au-detriment-de-son-propre-outil.html
[25] LinuxTricks, 11% parts de marché France — https://www.linuxtricks.fr/news/10-logiciels-libres/580-linux-a-11-de-parts-de-marche-en-france-e/
[26] WebProNews, Linux desktop mondial — https://www.webpronews.com/linux-desktop-market-share-climbs-to-4-7-by-2025-eyes-2026-breakthrough/
[27] TechCrunch, GitHub Copilot 20M users — https://techcrunch.com/2025/07/30/github-copilot-crosses-20-million-all-time-users/
[28] SecondTalent, GitHub Copilot statistics — https://www.secondtalent.com/resources/github-copilot-statistics/
[29] CNBC, Anthropic Series G — https://www.cnbc.com/2026/02/12/anthropic-closes-30-billion-funding-round-at-380-billion-valuation.html
[31] TechCrunch, projection revenus Anthropic 2028 — https://techcrunch.com/2025/11/04/anthropic-expects-b2b-demand-to-boost-revenue-to-70b-in-2028-report/
[32] LMSYS Chatbot Arena — https://arena.ai/fr/leaderboard
[33] Yahoo Finance, revenus OpenAI — https://finance.yahoo.com/news/openai-cfo-says-annualized-revenue-173519097.html
[34] L'Usine Digitale, Anthropic valorisation — https://www.usine-digitale.fr/article/anthropic-fait-exploser-sa-valorisation-apres-une-levee-de-fonds-de-13-milliards-de-dollars.N2237065
[35] Incremys, Statistiques Claude — https://www.incremys.com/ressources/blog/statistiques-claude
[36] Ollama, GitHub — https://github.com/ollama/ollama

[37] Apple Machine Learning Research, LLM M5 — https://machinelearning.apple.com/research/exploring-llms-mlx-m5

[38] TechCrunch, partenariat Apple-Google Gemini — https://techcrunch.com/2026/01/12/googles-gemini-to-power-apples-ai-features-like-siri/

[39] CNBC, IA chinoise Lunar New Year — https://www.cnbc.com/2026/02/13/china-ai-lunar-new-year-bytedance-baidu-tencent-alibaba.html

39-1
39-2
[40] CNBC, impact DeepSeek sur Nvidia — https://www.cnbc.com/2026/01/06/why-deepseek-didnt-cause-an-investor-frenzy-again-in-2025.html
[41] SQ Magazine, DeepSeek statistics — https://sqmagazine.co.uk/deepseek-ai-statistics/
[42] Interesting Engineering, robotique chinoise CES 2026 — https://interestingengineering.com/ces-2026/china-leads-humanoid-robotics-at-ces-2026
[43] CGTN, production robots humanoïdes Chine — https://news.cgtn.com/news/2026-01-10/Report-China-outpaces-U-S-in-2025-humanoid-robot-production-1JOuTfsew1i/p.html
[44] GlobeNewsWire, DJI parts de marché drones — https://www.globenewswire.com/news-release/2025/04/08/3057358/0/en/Connected-Commercial-Drones-Report-2025-Asia-Pacific-Leads-in-Drone-Adoption-with-DJI-Holding-a-Dominant-70-Global-Market-Share.html
[45] IDC, robots aspirateurs chinois — https://www.idc.com/resource-center/blog/the-rise-of-chinese-smart-vacuum-giants-and-the-fall-and-sale-of-irobot/
[46] DataMarket AI, DeepSeek vs Kimi — https://www.datamarketai.com/kimi-k1-5-vs-deepseek-r1-duel-des-meilleurs-llm-chinois/
[47] Cloud Summit, Mistral valorisation — https://cloudsummit.eu/blog/mistral-ai-14-billion-valuation-europe-turning-point
[48] Next.ink, Mistral Ministère des armées — https://next.ink/brief_article/le-ministere-des-armees-signe-un-accord-cadre-avec-mistral/
[49] Like2Byte, Mac Mini M4 DeepSeek R1 benchmarks — https://like2byte.com/mac-mini-m4-deepseek-r1-ai-benchmarks/
[50] Exo Labs, GitHub — https://github.com/exo-explore/exo
[51] Exo Labs Blog, DeepSeek V3 671B on Mac Mini cluster — https://blog.exolabs.net/day-2/
[53] PocketPal AI, GitHub — https://github.com/a-ghorbani/pocketpal-ai
[54] InfoQ, Cactus v1 on-device inference — https://www.infoq.com/news/2025/12/cactus-on-device-inference/
[55] CNBC, dissolution équipe Superalignment OpenAI — https://www.cnbc.com/2024/05/17/openai-superalignment-sutskever-leike.html
[56] Fortune, "The OpenAI Files" — https://fortune.com/2025/06/20/openai-files-sam-altman-leadership-concerns-safety-failures-ai-lab/

DAT as Code : automatiser la documentation technique avec l'IA

Arnaud Gaches — Mon, 15 Dec 2025 08:39:07 +0000

Introduction

L'année dernière, j'ai écrit un guide pour moderniser son DAT (Dossier d'Architecture Technique). Un an après, avec l'arrivée des coding assistants et leurs connecteurs, je me suis demandé : qu'est-ce qu'on peut vraiment faire avec l'IA pour maintenir un DAT ?

J'ai testé sur un projet Infra-as-code sur lequel je travaillais.
Objectif : partir de zéro et arriver à une doc complète (architecture + exploitation) avec le moins d'effort possible.

Spoiler : quelques heures de setup et ça marche.

La découverte : templates + prompts

Premier test avec un coding assistant : je lui donne un fichier markdown avec une structure (titres, sections) et j'y glisse des instructions dans des commentaires HTML .

Exemple: .

Et ça marche. Le coding assistant suit la structure et remplit chaque section selon les consignes.

## 🏗️ Prérequis

<!-- insérer prérequis techniques (Terraform et autres identifiés dans le code) -->

## Description de la gestion IAM

<!-- 
créer un fichier à partir du template TPL_README_IAM.md
insérer lien vers page iam
exemple: [IAM](./docs/doc_iam.md)
 -->

Ça peut paraître con mais c'est la méthode la plus efficace que j'ai testée pour garder une cohérence de style documentaire globale.

Le problème : 3 outils à synchroniser

Dans un projet classique, je jongle avec :

GitHub (code) : markdown en doc-as-code
Confluence (doc) : pour la recherche et facilité de lecture
Jira (ticket) : pour tracer les issues et projets

Maintenir la doc Confluence à jour à la main, c'est l'enfer.
On aimerait pouvoir le faire dans GitHub à côté du code, mais c'est moins pratique pour la recherche et la facilité de lecture.
Et on veut éviter de se retrouver avec de la redite partout.

Ce qui paraît le plus adapté, c'est écrire la doc avec le code et mettre Confluence à jour en conséquence, avec des liens et des références vers la doc sur GitHub.

La solution : MCP (Model Context Protocol)

Les MCP, c'est des connecteurs pour que ton coding assistant discute avec des services externes. J'en ai identifié trois essentiels pour ce projet :

Context7 : vérifie que la doc respecte les standards et détecte ce qui manque.

GitHub : lit le code (Terraform dans mon cas) pour extraire l'info architecture.

Atlassian : s'interface avec Confluence et Jira.

Setup

J'installe les 3 MCP dans mon IDE (VsCode dans mon cas, mais ça marche avec Cursor, IntelliJ, etc.).

Pour Atlassian, je configure en plus dans .vscode/settings.json :

{
    // Configuration MCP
    "mcp.confluence.enabled": true,
    "mcp.confluence.baseUrl": "https://votre-domaine.atlassian.net",
    "mcp.confluence.defaultSpace": "SPACE_KEY",
    "mcp.jira.enabled": true,
    "mcp.jira.baseUrl": "https://votre-domaine.atlassian.net",
    "mcp.jira.defaultProject": "PROJECT_KEY",
    "mcp.servers": {
        "confluence": {
            "command": "mcp-confluence",
            "args": [
                "--space",
                "SPACE_KEY",
                "--page-id",
                "PAGE_ID"
            ]
        },
        "jira": {
            "command": "mcp-jira",
            "args": [
                "--project",
                "PROJECT_KEY",
                "--board",
                "BOARD_ID"
            ]
        }
    }
}

Pour récupérer ces valeurs :

Confluence (https://domaine.atlassian.net/wiki/spaces/MON_ESPACE/pages/12345678/Titre)

SPACE_KEY = MON_ESPACE
PAGE_ID = 12345678

Jira (https://domaine.atlassian.net/jira/software/c/projects/MON_PROJET/boards/99)

PROJECT_KEY = MON_PROJET
BOARD_ID = 99

Je teste les connexions : ça passe ✓

Ensuite, je crée un repo GitHub avec mes templates de doc dans tpl_docs/ :

TPL_README.md : vue globale
TPL_README_IAM.md : IAM
TPL_README_FW.md : firewall
TPL_README_SIZING.md : sizing
TPL_README_PROCEDURE.md : procédures
TPL_README_DEX.md : dossier d'exploitation

Vous pouvez consulter les templates complets sur le repository GitHub.

Itération 1 : créer la documentation

Je crée une commande custom "create doc" dans agents.md (config du coding assistant) pour tout faire d'un coup.

Premier problème : l'assistant essaie d'accéder à mon dépôt GitHub privé sans authentification. Fail.
→ Fix : je précise dans agents.md d'utiliser le connecteur GitHub.

Deuxième problème : il commence à générer README, IAM, FW... et boom, dépassement de contexte (Claude Sonnet 4.5).

[INFO] Analyse du code Terraform... ✓
[INFO] Génération README.md... ✓
[INFO] Génération IAM.md... ✓
[INFO] Génération FW.md... ✓
[ERROR] Context length exceeded (125k tokens)
[FAIL] Process stopped

Conclusion : Fail. Il faut découper.

Itération 2 : itératif

Je modifie agents.md pour séparer le processus :

Analyse : inspection du Terraform
Plan : liste des docs à générer
Exécution : un doc à la fois, une conversation par doc

NEW CONVERSATION> Analyse le code
Analyse du code Terraform... ✓
[INFO] Génération du plan de documentation... ✓

NEW CONVERSATION> Génération README.md
[INFO] Génération README.md... ✓

NEW CONVERSATION> Génération IAM.md
[INFO] Génération IAM.md... ✓

NEW CONVERSATION> Génération FW.md
[INFO] Génération FW.md... ✓

NEW CONVERSATION> Génération SIZING.md
[INFO] Génération SIZING.md... ✓

[SUCCESS] Documentation complète générée

Résultats :

Analyse + plan : ✓
Génération séquentielle : ✓ (mais c'est long)
Doc complète : ✓

Finalement, l'itératif, c'est le bien.

Petit souci restant : c'est verbeux. Je dois retravailler les prompts dans les templates pour lui dire de faire court ("5 lignes max").

Itération 3 : doc d'exploitation

Avec l'itération 2, je génère la doc d'architecture.
Je voudrais maintenant ajouter la documentation sur l'exploitation (DEX avec SLA, fiche DICT, monitoring, sauvegarde, et les procédures d'exploitation sur les composants).

Là où c'est pertinent : le coding assistant est doué pour écrire les procédures avec les commandes précises.

En plus d'écrire dans la procédure "réattacher le disque à la VM", le coding assistant me donne la commande technique précise :

gcloud compute instances attach-disk instance-1 --disk=disk-1 --zone=europe-west1-b

Ça apporte une valeur ajoutée à la procédure technique et ça évite ensuite de perdre 10 minutes à rechercher/deviner la syntaxe de la commande.

J'ajoute TPL_README_DEX.md et TPL_README_PROCEDURE.md, je mets à jour agents.md.

Problème : toujours trop verbeux. Je continue d'affiner les prompts.

Itération 4 : publication dans Confluence

Maintenant je veux publier dans Confluence, avec une séparation claire architecture / exploitation.

Deux petits challenges :

Un template "procédure" → plusieurs pages (une par composant : DB, load balancer, etc.)
Faire comprendre au coding assistant les macros Confluence (notamment pour les diagrammes Mermaid)

Ma stratégie :

GitHub (source) :

README.md, IAM.md, FW.md, SIZING.md, DEX.md, PROCEDURE_*.md

Confluence (publication) :

Page "Application" : page racine du projet
- Sous-page "Architecture" : liens vers GitHub + résumés
- Sous-page "Exploitation" : lien DEX + procédures

Itération 5 : GitHub Actions (en cours)

Premier test : tout régénérer

Une GitHub Action par type de doc.

analyse → crée des issues Jira Doc:xxx
update-iam, update-fw, update-dex → traitent chaque issue

Problème : ça régénère tout à chaque fois, même ce qui n'a pas bougé.

Deuxième test : détection d'écarts

Je teste une approche différente :

Code ↔ Doc : le code a changé sans update de doc ?
Confluence ↔ Doc : désync ?
Template ↔ Doc : le standard a évolué ?

Pour chaque écart → issue Jira → traitement ciblé.

Je commence mes tests pour valider si c'est plus pertinent.
Et là, c'est la course de fin d'année et un manque de temps pour finir donc désolé de vous laisser sur votre faim.

Bilan

Ce que ça donne

Temps :

Config (MCP + settings) : 1h
Exécution complète : < 1h (1 plan + plusieurs docs)
Création des templates (simples) : 1h
Total : 3h du repo vide à la doc complète

Résultat :

Schémas d'archi
Doc IAM et firewall
Doc exploitation avec procédures
Page Confluence propre

Un modèle adaptable
Ici le repo github était un repo IaaS avec des templates adaptés (archi, réseau, sizing, iam).
Mais le principe global fonctionne : il est très facile de l'adapter et de l'utiliser sur le(s) repo(s) souhaité(s) pour faire la doc souhaitée

Les limites

Il faut quand même relire.
Le coding assistant peut :

Se tromper techniquement
Approximer des choses, souvent les nombres
Halluciner des informations

Le mot de la fin : Assistant, pas remplaçant

Bilan de cette fin d'année 2025 : J'ai voulu avancer sur l'automatisation en CI/CD mais je ressentais un frein à vouloir aller dessus.

J'ai enfin compris pourquoi :

Si techniquement, on pourrait brancher ces agents en CI/CD pour une génération "au kilomètre" sans supervision, je pense en fait que ce serait une erreur.

La documentation technique n'est pas qu'une liste d'éléments techniques :

Elle a un but, elle doit pouvoir transmettre la compréhension d'un système.

(rappellez-vous Diataxis !)

L'IA excelle pour transformer du code en phrases et structurer l'information (merci Diataxis), mais elle n'a pas la "conscience" du contexte (métier, applicatif, technique).

Et elle a aussi du mal à "maintenir l'intérêt" du lecteur.

Or, si tout le monde se dit "chouette, la doc est automatisée", plus personne ne prendra le temps de relire et de valider ce que l'IA a écrit...

La documentation sera longue, verbeuse, incipide et remplie d'erreurs.

Et on lui retirera son rôle de source de vérité.
Et le DAT redeviendra un document mort que personne ne voudra aller lire.

L'état de l'art en 2025 ne doit pas viser le "zéro effort" :

L'IA supprime la page blanche et la pénibilité de la mise en forme. Elle nous donne le temps de nous concentrer sur la vraie valeur ajoutée : l'analyse, la décision, et la stratégie.

Prochaine étape ? S'attaquer aux ADR (Architecture Decision Records).

Pour l'instant, l'IA sait décrire ce qui existe, mais il est encore compliqué d'expliquer pourquoi nous avons pris telle décision plutôt qu'une autre.

Cepndant, intégrer les ADR dans les moeurs progresse : avoir une IA secrétaire pour enregister les différents éléments et en rédiger un document d'ADR propre et structuré peut aider à cette adhésion.

Et du coup, ça, c'est mon prochain chantier.

J'espère que cet article vous aura inspiré et motivé à avoir une documentation propre.

Si vous découvrez le sujet et souhaitez comprendre les fondations de ce "dinosaure numérique" qu'est le DAT, je vous redonne le lien vers ma série précédente pour aller plus loin :
https://dev.to/agaches/series/29201

Encore merci à Benjamin MARSTEAU pour son énergie positive dans l'organisation de cet Advent of Tech,
Merci à mes relecteurs Emilie RESPINGUE et Yann SCHEPENS.
Bravo à tous les autres participants pour leurs articles.
Enfin Merci à vous de m'avoir lu jusque là.

Je vous souhaite de très bonnes fêtes de fin d'années et à l'année prochaine !

Vous pouvez retrouver les autres articles de l'Advent of Tech 2025 de Onepoint/Wepoint ici :
https://www.groupeonepoint.com/fr/publications/calendrier-de-lavent-tech-2025/

Arrêtez de demander au LLM si c'est bien. Demandez-lui ce qui cloche.

Arnaud Gaches — Wed, 10 Dec 2025 08:41:49 +0000

Introduction : La boucle de l'enfer

Il y a quelques mois, pour un talk technique, j'ai demandé à Claude une revue : "Qu'en penses-tu ?"

V1 : "Excellent ! Solide."
V2 (après retouches) : "Génial ! Mais ça a plus de sens d'inverser A et B, et rajoutes un sujet manquant sur C."
V3 (après modifs) : "Parfait ! Pour améliorer la fluidité, il faudrait inverser B et A. Et C me parait inutile."

J'ai compris ce soir-là que l'IA préférait me répondre positivement plutôt que de me dire ce qui clochait. Ce comportement de "Yes Man" n'est pas un bug, c'est un défaut de conception documenté.

Le problème : le biais de complaisance des LLM

La "sycophancy" (complaisance) : un défaut documenté

Les grands modèles de langage (ChatGPT, Claude, Gemini, etc.) montrent systématiquement de la complaisance (sycophancy[EN]) : ils ont tendance à valider les opinions de l'utilisateur plutôt que de les contredire, même lorsque ces opinions sont incorrectes [1].

Le coupable : le réentraînement (Reinforcement Learning from Human Feedback - RLHF)

Le réentraînement des modèles (RLHF) favorise les réponses qui plaisent aux évaluateurs humains plutôt que la vérité objective. Paradoxalement, plus un modèle est grand et entraîné, plus il devient complaisant [2].

Résultat : Le modèle est optimisé pour votre satisfaction immédiate, pas pour la vérité.

Les conséquences concrètes critiques

Des études récentes montrent que les LLM changent leurs réponses lorsqu'elles sont contestées, même quand leur réponse initiale était correcte.

Concrètement, une simple remise en question (ex: "T'es sûr ?") peut pousser le LLM à changer sa réponse par pression sociale, validant l'utilisateur au détriment de la vérité [3].

La solution : les personas négatifs

Le changement de formulation transforme radicalement les retours :

Prompt	Type de retour obtenu
"Analyse ce document"	Feedback positif générique + suggestions molles
"Critique ce document"	Critiques ouvertes du document
"Tu es un concurrent. Comment tu attaquerais ce doc ?"	Identification de vraies faiblesses

Astuce : Précisez au modèle que ce document n'est pas le vôtre (ex: "J'ai reçu ce brouillon d'un collègue..."). Cela désactive le filtre de politesse du modèle qui cherche à ne pas vous vexer.

Pourquoi ça marche ?

Contrainte de l'adversaire

En imposant un rôle critique, vous créez une tension dans le prompt : l'IA doit choisir entre respecter votre consigne (être critique) et suivre son biais de complaisance (être positive).

Le prompt adversarial augmente la probabilité de réponses critiques sans éliminer complètement le biais.

Simuler l'adversité avant qu'elle arrive

Les personas négatifs sont un stress-test documentaire. Ils simulent les objections réelles dans un environnement contrôlé.

Cette approche s'inspire de méthodes éprouvées :

Red teaming en cybersécurité : des équipes attaquent leurs propres systèmes pour trouver les vulnérabilités
Stress tests bancaires : les banques testent leurs portefeuilles avec des scénarios catastrophes (régulation Bâle III)
Murder boards militaires/corporate : des panels dont le job est de détruire votre argumentaire avant la vraie présentation

Remplacement d'un lecteur externe

Si un LLM lit votre doc et ne comprend pas vos propos, un lecteur pressé risque de ne pas le comprendre non plus.

Par ce test, elle devient un indicateur de complexité en identifiant le langage spécifique à votre domaine qu'elle ne maitrise pas (et que donc un lecteur externe ne maitrise pas non plus).

Limites et bonnes pratiques

1. Faux positifs : la règle des "2+ personas"

Le LLM peut inventer des problèmes pour satisfaire la consigne.
Règle : Si 2+ personas pointent le même problème → c'est probablement réel. Sinon, vérifiez.

2. Manque de contexte

Avec un contexte vide, le LLM ignore le contexte et l'historique interne de votre entreprise.
Utilisez sa "naïveté" comme un atout : c'est un test d'accessibilité pour un lecteur externe.

3. Diversifier les angles de vue

Pour un résultat optimal, mélangez les retours : combinez des critiques sur la forme (écriture, cohésion) et sur le fond (logique, pertinence stratégique).

Next step : Passez à l'offensive

Tant que vous chercherez la validation dans vos prompts, vous obtiendrez de la complaisance.
Pour transformer vos documents, vous devez changer vos prompts.

Votre boîte à outils pour commencer

Pour vous éviter de partir d'une page blanche, j'ai compilé et testé une série de "Personas Négatifs" prêts à l'emploi. Ce catalogue à faire évoluer contient des prompts pour :

Simuler un CFO obsédé par le ROI.
Incarner un Concurrent agressif.
Jouer le rôle d'un Lecteur pressé qui décroche au moindre flou.

👉 Accéder au Catalogue de Prompts Négatifs

Mode d'emploi express (15 min chrono)

Voici comment procéder :

Choisissez 2 Personas opposés (ex: un CFO pour les chiffres + un Concurrent pour la stratégie).
Ouvrez une conversation vierge pour chaque persona (pour éviter la contamination du contexte).
Copiez-collez le prompt + votre texte.
Compilez uniquement les critiques qui reviennent 2 fois. Le reste, c'est du bruit.

La preuve par l'exemple : le crash-test de cet article

Pour ne pas reproduire l'erreur de mon talk réseau, j'ai appliqué cette méthode sur l'article que vous lisez. Je suis parti d'un premier brouillon bavard (consultable ici : l'article original avant critique et je l'ai fait passer à la moulinette de 3 prompts itératifs.

1. Le prompt "Valeur" (pour élaguer)

*"Identifie dans ce document :

Les paragraphes qui n'apportent pas de valeur (pure rhétorique)

Les sections qui manquent de substance

Le ratio contenu utile / remplissage

Les zones où l'on pourrait être plus concis Fournis un % de contenu "utile" vs "remplissage" pour chaque section."*

2. Le prompt "Cohérence" (pour structurer)

"Analyse ce document en vérifiant :
La cohérence logique du début à la fin
Les éventuelles contradictions entre sections
Les ruptures dans le fil narratif
Les redondances inutiles"

3. Le prompt "Qualité perçue" (pour crédibiliser)

"Tu es un lecteur qui sature des articles putaclic et des machins générés par IA.

Évalue :

La rigueur de l'argumentation (1-10)

La qualité des sources et références (1-10)

Le professionnalisme du ton (1-10)

La précision des données (1-10)

Qu'est-ce qui te fait penser "article de qualité" vs "article bof" "

4. Le prompt "Journaliste expérimenté" (pour finaliser)

"Tu es un journaliste expérimenté.
La personne est un amateur qui apprécie un style simple, direct, concret, qui parle un peu de lui et avec un peu d'humour.
Reprends une analyse en profondeur de l'article en résultat et donnes-en un avis."

Les scores avant/après :

Ratio % utile : Passée globalement de 60% à 96%
Qualité perçue : Note passée de 4/10 (argumentaire mou) à 9/10 (logique implacable).

Le plus parlant ? L'introduction.

La version brouillon s'étalait sur 12 lignes de narration personnelle ("Je devais préparer un talk... J'ai la connaissance technique..."). Je me rendais compte qu'il fallait simplifier, réduire.

La version finale tient en 6 lignes qui posent le problème sans rentrer dans les détails superflus.

Le lien vers la première version pour la comparaison :

👉 Accéder à l'ancien article

L'Avis final du journaliste: C'est un article solide, utile et agréable à lire. Il ne cherche pas à impressionner par la complexité, mais à convaincre par l'efficacité.

Le mot de la fin

Ne me croyez pas sur parole, essayez.
Prenez votre dernier brouillon, et testez divers prompts (même au hasard).

Essayez le prompt du "CFO Sceptique" sur vos propositions commerciales.

Essayez le prompt du "Le Bullshit Detector" sur les dernières communications sur l'IA.

Regardez votre texte se faire démolir... avec tous les axes identifiés pour pouvoir mieux le reconstruire.

Merci d'avoir lu jusqu'ici. Et j'en profite pour remercier tous mes relecteurs et relectrices.

Vous pouvez retrouver les autres articles de l'Advent of Tech 2025 de Onepoint/Wepoint ici :
https://www.groupeonepoint.com/fr/publications/calendrier-de-lavent-tech-2025/

Sources

[1] Perez et al., Anthropic 2022 - "Discovering Language Model Behaviors with Model-Written Evaluations". Étude sur 12 modèles différents montrant que le taux d'accord avec l'utilisateur augmente systématiquement avec la taille du modèle.

[2] Malmqvist 2024 - "Sycophancy in Large Language Models: Causes and Mitigations". Revue technique analysant les causes, les impacts et les stratégies d'atténuation de la complaisance dans les LLM.

[3] Étude DeepMind 2024 citée dans Computerworld, mars 2024. Les LLM modifient leurs réponses sous pression sociale, même quand ils avaient raison initialement.

Moderniser son Dossier d'Architecture Technique : Guide pratique pour 2024

Arnaud Gaches — Tue, 24 Dec 2024 08:30:00 +0000

🎁 Enfin ce guide tant attendu !

Mes articles précédents vous ont démontré que :

Le DAT est un dinosaure numérique
Les mêmes erreurs se répètent dans les DAT
Diataxis peut structurer une documentation désorganisée
Les Architecture Decision Records (ADR) complètent efficacement le DAT

J'imagine que vous avez déjà des idées qui commencent à germer, et je vais vous accompagner dans cette réflexion.

J'espère être parvenu à vous faire prendre conscience que la modernisation du DAT ne peut se faire de manière isolée.
Elle s'inscrit dans une démarche plus large de modernisation de toute notre documentation technique.

Cette prise de conscience est importante : moderniser son DAT, c'est d'abord moderniser son organisation et sa documentation.
C'est pour cela qu'avant toute action concrète, il est essentiel de poser les bases d'une transformation réussie.

Vous connaissez l'histoire des cordonniers mal chaussés.

Sommaire :

1. Poser les bases : L'ADR fondatrice
- ADR : Définir une organisation documentaire
2. Mettre en place une gouvernance documentaire
- Planification des revues
- Gestion de la dette documentaire
3. Mise en œuvre
- Méthode de mise en oeuvre
- Migration progressive
4. Les aides pour cette migration
- Bonnes pratiques et pièges à éviter
- Outillage : Documentation-as-code
- Documentation des Flux échanges inter-applicatifs
- Exemples de structures documentaires
  - Structure simple alignée sur Diataxis
  - Structure complexe basé sur un modèle de dossier applicatif
5. Mesures et retours d'expérience
- Mesurer le succès de la transformation
- Exemple de Planning détaillé de migration sur 6 mois
- Exemple concret de transformation réussie
Que devient le DAT ?
Conclusion

1. Poser les bases : L'ADR fondatrice

La première étape consiste à créer une ADR fondamentale pour votre transformation :

ADR : Définir une organisation documentaire

Rassemblez toutes les parties prenantes pour définir collectivement :

L'état actuel de la documentation
Les problèmes à résoudre
Les besoins des différentes équipes
Les contraintes techniques et organisationnelles

Puis choisir collectivement parmis les scénarios possibles :

La structure hiérarchique de la documentation
Les outils et technologies à utiliser
Les rôles et responsabilités de chaque équipe
Le processus de mise à jour et de validation

2. Mettre en place une gouvernance documentaire

Planification des revues

La documentation doit redevenir une activité régulière :

Revue (mensuelle?) des guides et procédures
Revue *(trimestrielle?) *de la documentation de référence
Création d'ADR pour chaque décision majeure
Mise à jour des schémas lors des changements d'architecture

La documentation se met à jour en même temps que les sujets techniques
La charge des actions techniques inclue la documentation (ne la sous-estimez pas)

Recommandation : En contexte agile, intégrez la revue documentaire dans la préparation des PI Planning.

Gestion de la dette documentaire

Traitez la documentation comme vous traitez le code code :

Créez des tickets pour la dette documentaire
Lors des incidents, indiquer aussi la dette documentaire
Priorisez les mises à jour nécessaires
Planifiez les tâches de documentation dans les sprints
Mesurez la progression

3. Mise en œuvre

La préparation peut être complexe.
La mise en oeuvre, elle, reste simple.

Méthode de mise en oeuvre

Pour chaque solution/socle technique dont vous voulez revoir la documentation :

Inventorier la documentation existante
Classifier le contenu selon Diataxis :
- Tutoriels
- Guides
- Références
- Concepts
Identifier la cible pour le contenu dans la structure documentaire
Identifier la dette documentaire
Planifier les actions nécessaires (responsable, périmètre)
Réaliser les actions de mise à jour

Migration progressive

La migration doit être progressive et planifiée :

Commencer par les documents les plus consultés
Migrer en parallèle de l'existant
Valider avec les utilisateurs
Mettre à jour les références

Conseil : Demandez aux nouveaux membres de l'équipe de relire et critiquer la documentation. Leur regard neuf est précieux.

4. Les aides pour cette migration

Bonnes pratiques et pièges à éviter

✅ Bonnes pratiques

Former les équipes aux nouveaux outils
Maintenir un glossaire commun
Vérifier régulièrement les liens
Documenter au fil de l'eau
Communiquer sur les changements

❌ Pièges à éviter

Vouloir tout migrer d'un coup
Négliger la formation des équipes
Oublier de vérifier l'accessibilité

Outillage : Documentation-as-code

Le concept est simple :

S'appuyer sur des langages à faible balisage (Markdown, AsciiDoc) pour gérer le contenu riche comme du code et pouvoir y appliquer toutes les bonnes pratiques que l'on connait (versioning, publication, revue, merge, ...)

Pour une présentation détaillée de la Documentation-as-code, consultez la série d'articles de Nicolas Giraud :
https://dev.to/onepoint/Documentation-as-code-petit-guide-illustre-pour-mieux-se-lancer-2m2k

Cette approche permet de :

Partager et intégrer des documents dans des structures complexes
Documenter en parallèle du développement (code applicatif ou infrastructure)
Versionner et publier selon des stratégies documentaires élaborées
Propager automatiquement les mises à jour grâce aux références

Point clé : La documentation suit les évolutions du code.

Les documents peuvent être publiés ou intégrés pour générer de nouvelles documentations.

Documentation des Flux échanges inter-applicatifs

Identifier la solution ou le socle responsable de ces échanges.

C'est son équipe qui portera la documentation de ces échanges.

Les autres pourront faire référence à cette documentation.

Exemples de structures documentaires

Diataxis propose quatre types de documentation fondamentaux.
Cette structure peut servir de base, mais doit s'adapter aux besoins des utilisateurs.

L'organisation doit rester logique pour les utilisateurs, qu'elle soit simple ou complexe.

Les fonctionnalités de documentation collaborative (tags, labels) permettent des vues multiples.

Structure simple alignée sur Diataxis

Exemple de structure documentaire simple

📁 Documentation technique
├── 📁 Concepts et ADR
│   ├── Vue d'ensemble
│   └── Décisions d'architecture
├── 📁 Références techniques
│   ├── Architecture fonctionnelle
│   ├── Architecture applicative
│   ├── Architecture technique
│   └── Schémas et descriptions
├── 📁 Guides
│   ├── Installation
│   └── Exploitation
└── 📁 Onboarding
    └── Premiers pas

Lien vers exemple concret

Structure complexe basé sur un modèle de dossier applicatif

Pour des besoins plus spécifiques, le modèle de documentation applicatif propose une structure plus élaborée, basée sur différentes vues :

📁 Documentation
├── 📁 Vue Métier
│   ├── 🎓 Tutoriels
│   │   └── Découverte des processus métier
│   ├── 📚 Référence
│   │   ├── Exigences métier détaillées
│   │   ├── SLAs et niveaux de service
│   │   └── Volumétrie attendue
│   ├── 📖 Guides
│   │   └── Comment définir de nouvelles exigences
│   └── 💡 Concepts
│       └── Principes métier structurants
│
├── 📁 Vue Applicative
│   ├── 🎓 Tutoriels
│   │   └── Premier développement sur l'application
│   ├── 📚 Référence
│   │   ├── Architecture technique détaillée
│   │   ├── Interfaces et APIs
│   │   └── Composants logiciels
│   ├── 📖 Guides
│   │   ├── Comment ajouter un nouveau composant
│   │   └── Comment modifier une interface
│   └── 💡 Concepts
│       └── Patterns d'architecture utilisés
│
├── 📁 Vue Infrastructure
│   ├── 🎓 Tutoriels
│   │   ├── Premier déploiement
│   │   ├── Configuration initiale supervision
│   │   └── Mise en place sauvegarde
│   ├── 📚 Référence
│   │   ├── Composants et versions
│   │   ├── Matrice des flux techniques
│   │   ├── Spécifications timeouts
│   │   ├── Caractéristiques environnements
│   │   └── Configuration supervision
│   ├── 📖 Guides
│   │   ├── Démarrage/Arrêt des composants
│   │   ├── Sauvegarde/Restauration
│   │   ├── Mise en maintenance
│   │   ├── Gestion des logs
│   │   └── Déploiement nouvelle version
│   └── 💡 Concepts
│       ├── Modèle de disponibilité
│       ├── Principes de résilience
│       ├── Stratégie de sauvegarde
│       └── Architecture supervision
│
└── 📁 Vue Transverse
    ├── 🎓 Tutoriels
    │   ├── Mise en place sécurité
    │   └── Configuration performance
    ├── 📚 Référence
    │   ├── Exigences sécurité
    │   ├── Métriques performance
    │   └── Standards techniques
    ├── 📖 Guides
    │   ├── Audit sécurité
    │   ├── Optimisation performance
    │   └── Gestion charge
    └── 💡 Concepts
        ├── Principes de sécurité
        ├── Stratégie performance
        └── Écoconception

Vous avez ici le meilleur des 2 mondes. Le modèle DA et ses vues, redécoupé dans une structure Diataxis et qui évite des documents trop longs.

A RETENIR :
Diátaxis n'est pas un schéma de 4 boites dans lequel la documentation doit être placée.

Diataxis n'impose pas une structure rigide à quatre compartiments.
Il définit quatre types de documentation à organiser selon les besoins.

5. Mesures et retours d'expérience

Mesurer le succès de la transformation

Définissez des indicateurs clés :

Métriques quantitatives
- Temps moyen de recherche d'information
- Taux de consultation de la documentation
- Nombre de mises à jour par période
- Délai entre un changement technique et sa documentation
Métriques qualitatives
- Satisfaction des équipes (sondages réguliers)
- Qualité des retours des nouveaux arrivants
- Réduction des questions récurrentes
- Autonomie accrue des équipes

Conseil : Mesurez une baseline avant la transformation pour mesurer la progression de l'amélioration

Exemple de Planning détaillé de migration sur 6 mois

Mois 1-2 : Préparation

Semaine 1-2 : ADR fondatrices
Semaine 3-4 : Audit documentation existante
Semaine 5-6 : Formation des équipes
Semaine 7-8 : Mise en place des outils

Mois 3-4 : Migration pilote

Documentation d'un composant critique
Tests des processus de mise à jour
Retours d'expérience et ajustements
Nouvelles ADR selon décisions

Mois 5-6 : Déploiement général

Migration progressive des autres composants
Mise en place des revues régulières
Formation continue des équipes

Conseil : Adaptez ce planning selon votre contexte et vos contraintes

Exemple concret de transformation réussie

Prenons l'exemple d'une équipe gérant une application métier avec un éditeur :

Avant

2 versions de DAT monolithique Word de 200 pages (un éditeur, un client) stockés chacun dans un endroit différent
Un DEX monolithique Word stocké dans un autre endroit
Pas de schéma ni description de l'architecture technique
Pas de documentation d'installation

Après

Documentation structurée selon Diataxis
Un seul point d'entrée
Schémas globaux en draw.io
Schémas spécifiques générés depuis le code infrastructure (markdown mermaid)
ADR pour chaque décision majeure
Références entre documentation et Infra-as-code

Bénéfices constatés

Revue d'architecture validée simplement (infrastructure et sécurité)
Retour positifs sur documentation claire et complète
Amélioration des actions techniques sur la plateforme (référence aux procédures plus facile)
Documentation complète du périmètre technique et applicatif
Les autres équipes profitent de la documentation sur l'installation technique des composants pour prendre exemple dessus (ce sont les premiers résultats dans l'outil de gestion documentaire interne)

Défauts constatés

Encore très loin d'être parfait
Plusieurs documents dont les schémas d'architecture ont été stockés sur du Google Drive derrière : pas d'accès pour les autres équipes. (ça va être corrigé)

Que devient le DAT ?

Le DAT traditionnel se fond dans la documentation générale. Trois approches sont possibles si on vous le demande :

Fournir les liens vers les références techniques
Générer une documentation à partir des éléments existants
Extraire les sections pertinentes du système documentaire

Conclusion

Cela va faire cliché mais la modernisation du DAT est un voyage, pas une destination. Elle demande :

Une vision claire de l'objectif
L'implication de toutes les équipes
Une approche progressive et structurée
Un suivi régulier

L'important n'est pas d'avoir une documentation parfaite, mais une documentation vivante et utile qui évolue avec vos besoins.

J'espère avoir :

Éclairé votre compréhension du DAT
Réconcilié les approches modernes avec les besoins documentaires
Fourni des réponses pratiques pour vos transformations

De mon côté, je réfléchis déjà à l'impact des LLM sur l'évolution de la documentation technique en 2025.
Pensez-y : Qui mieux qu'un LLM (une IA) pour comprendre un langage informatique et le convertir en une documentation claire et simple ?
Imaginez des schémas d'architecture et des matrices de flux qui se mettent à jour automatiquement au fil des évolutions de notre code Terraform...
Moi je n'imagine plus, je l'ai testé.
Tiens, ça me donne une idée pour un prochain article : hummm "Documentation technique et IA : le DAT en 2025" 😉

Merci beaucoup de votre lecture jusque là,
Je serais ravi que vous me partagiez vos retours et critiques.

Cet article fait partie du "Advent of Tech 2024 Onepoint", une série d'articles tech publiés par Onepoint pour patienter jusqu'à Noël.
Voir tous les articles du Advent of Tech 2024

Architecture Decision Record : Documenter le pourquoi, pas juste le comment

Arnaud Gaches — Fri, 13 Dec 2024 08:30:00 +0000

Cet article fait suite à mon précédent article :
https://dev.to/onepoint/documentation-chaotique-diataxis-a-la-rescousse--3e9o

Quand on parle de ce dinosaure de DAT, il y a malgré tout un sujet à la mode : les Architecture Decision Records (ADR).

Créé par Michael Nygard en 2011, cette pratique gagne en popularité depuis quelques années. En 2024, nous pouvons en faire un passage obligé de la documentation technique d'architecture, surtout si on veut moderniser le DAT.

Dans cet article, je vous propose un tour d'horizon des ADR et de leurs bénéfices.

Sommaire :

Définition d'une Architecture Decision Record
- Structure d'une ADR
  - En-tête
  - Contexte
  - Solutions envisagées
  - Décision
  - Implications
- Modèles disponibles
Bénéfices des ADR
- Transparence et traçabilité
- Facilitation de la prise de décision
- Amélioration de la maintenabilité
- Intégration simplifiée des nouveaux collaborateurs
- Prise de décision apaisée
ADR : Le chaînon manquant
Conclusion

Définition d'une Architecture Decision Record

Une ADR est à la fois une réunion et son compte-rendu portant sur une décision d'architecture.

Une ADR vise à réunir tous les sachants techniques concernés pour prendre une décision d'architecture collégiale sur une problématique et d'en identifier les implications.

Chaque participant peut exprimer librement sa vision et son point de vue.
La décision finale doit être collégiale et unanime.

Structure d'une ADR

En-tête

Titre (de l'ADR)
Date de la décision
Statut (proposé, accepté, rejeté, remplacé, déprécié, etc.)
Participants à la décision
(Optionnel) Identifiant unique pour référence
(Optionnel) Portée de l'ADR (solution, application, inter-applicatif, domaine, entreprise)

L'entête doit permettre d'identifier rapidement la portée, le statut, la date et les participants de l'ADR.

Contexte

Situation actuelle
Problématiques à résoudre
(Optionnel) Contraintes (métier et techniques)
(Optionnel) Exigences (normes, sécurité, métier, technique, standards)
(Optionnel) Hypothèses

Le contexte doit exposer de manière simple la question/problématique à laquelle l'ADR doit apporter une réponse.
Dans l'idéal, on évitera de mêler plusieurs problématiques au sein d'une même ADR.

Solutions envisagées

Description des scénarios possibles
(Optionnel) Avantages et inconvénients de chaque scénario

Les solutions et scénarios techniques envisagés doivent être clairement détaillés avec leurs avantages et inconvénients (technique, coût, qualité, délai, ...)

Décision

Choix du scénario retenu
Justification du choix
(Optionnel) Motifs de rejet des autres scénarios

La décision doit être justifiée. Idéalement, on indique ET les motifs du choix de scénario ET les motifs de rejets des autres scénarios

Implications

Impacts identifiés
Risques anticipés
Références aux ADR connexes (notamment celles remplacées)
(Optionnel) Références documentaires
- (Optionnel) Cadrage projet (plan d'action, planning, ressources, charges)
- (Optionnel) Critères de succès (métriques de suivi, indicateurs de performance)

La structure guide les échanges et sert de livrable final pour documenter la décision.

Une ADR possède un statut et suit un cycle de vie documentaire.
Elle reste valide tant que :

La solution associée existe
elle n'est pas remplacée par une nouvelle ADR

On fait donc référence dans les nouvelles ADR aux ADR qui sont remplacées

Modèles disponibles

J'ai adapté en français des templates anglais que j'appréciais :
ADR simple
ADR avancé
ADR exhaustif

C'est avant tout pour vous montrer des exemples de formes d'ADR.
Vous pouvez librement vous en inspirer selon vos besoins.

Bénéfices des ADR

Transparence et traçabilité

Les ADR, en tant que comptes-rendus, assurent :

La transparence des décisions prises
La traçabilité des choix effectués
Un meilleur suivi de la dette technique associée

Fini les justifications du type "c'est historique" ou "les personnes concernées ont quitté l'entreprise"

Facilitation de la prise de décision

Les ADR :

Structurent les discussions
Permettent des décisions éclairées
Documentent les implications des choix (dettes, contraintes)

La méthode demande d'examiner les différents choix et de justifier
pour le choix fait, quelles sont les raisons qui ont amené à ce choix
pour les autres, les raisons de leur non-sélection

Amélioration de la maintenabilité

Les ADR permettent :

La conservation de l'historique décisionnel
Une meilleure compréhension du système et de son évolution
Une gestion facilitée de la dette technique

Cette approche implique une gestion documentaire qui permet de retrouver toutes les ADR et de les trier par ordre chronologique.

Intégration simplifiée des nouveaux collaborateurs

Les nouveaux membres comprennent mieux l'historique des choix architecturaux du système.

Cette approche vous retire la difficulté de répondre à la question "Mais pourquoi vous avez fait comme ça ?"

Prise de décision apaisée

Les décisions d'architecture, quand elles sont documentées, se dispersent généralement entre :

Les comptes-rendus de comités (COPRO/COPIL/COSTRAT)
Le DAT qui tente de couvrir tous les aspects (qui, quoi, comment, pourquoi)

Cette dispersion peut créer des situations complexes, comme l'illustre cette expérience personnelle :
J'accompagnais une équipe ayant choisi une migration Cloud type "lift and shift", sans services managés.
Quelques mois plus tard, l'apparition d'un nouveau service managé a créé des doutes dans l'équipe :

Devons-nous changer notre approche ?
Est-ce trop tard ?
Pourquoi ne l'a-t-on pas anticipé ?
Quel serait le coût d'un changement de direction alors qu'on approche de la fin ?

L'organisation d'une ADR nous a permis de :

Réévaluer les différents scénarios possibles
Intégrer les nouvelles informations sur le service managé
Comparer objectivement les coûts et bénéfices de chaque option
Documenter clairement le raisonnement derrière notre choix final

Ce cadre structuré a permis à l'équipe de prendre une décision éclairée, basée sur des critères objectifs plutôt que sur des impressions ou des craintes.
Faire cette ADR a transformé une situation stressante pour l'équipe en un processus de décision constructif et argumenté.

Voici l'exemple de cette ADR anonymisée :
ADR migration lift and shift

Prenons un autre exemple très parlant, une équipe face à un dilemme :
D'un côté, le standard de l'entreprise à respecter.

De l'autre, une date de mise en production incompatible avec la disponibilité de ce standard.

L'ADR a structuré la décision en deux temps :

Déployer d'abord une solution non-standard pour respecter les délais
Planifier ensuite une migration vers le standard

La dette technique a été précisée : un écart temporaire aux standards, clairement documenté et une remédiation planifiée.

ADR : Le chaînon manquant

Les ADR sont une réponse au besoin de documentation des décisions d'architecture. Leur adoption améliore la qualité et la pérennité des solutions techniques et de leurs dettes techniques.

Elles peuvent être un vrai levier de décision entre priorité métier et obsolescence technique.

Leur dimension temporelle nous permet aussi de :

Mieux Comprendre le contexte de l'époque (comme "à ce moment-là, l'outil Z n'était pas encore assez développé")
Evaluer si ces décisions sont toujours pertinentes aujourd'hui
Éviter de juger les choix passés avec nos connaissances actuelles

Le plus gros bénéfice selon moi est de permettre d'avoir des discussions plus constructives et apaisées :
Au lieu de critiquer les anciens choix ou les priorités, on peut avoir des échanges plus sereins et objectifs, même sur des sujets difficiles.

La priorité peut être faite au métier en échange d'un engagement de remédiation de la dette technique.

Conclusion

En commençant à utiliser les ADR, j'ai compris que leur usage apportait un autre bénéfice pour le DAT.

En séparant la documentation des décisions, le DAT n'a plus à porter la charge de leur justification :

Les décisions gagnent en visibilité.
Le DAT perd du poids et gagne en lisibilité

Vous comprenez à présent pourquoi je voulais vous parler d'ADR dans le cadre de la modernisation du DAT.

Cet article fait partie du "Advent of Tech 2024 Onepoint", une série d'articles tech publiés par Onepoint pour patienter jusqu'à Noël.
Voir tous les articles du Advent of Tech 2024

Merci pour votre lecture.

Documentation chaotique ? Diataxis à la rescousse !

Arnaud Gaches — Thu, 12 Dec 2024 08:30:00 +0000

Cet article fait suite à mon précédent article :
https://dev.to/onepoint/les-peches-capitaux-du-dossier-darchitecture-technique-111p

Dans le monde tech, je trouve qu'un paradoxe persiste :
Nous avons mis en place des outils ultra-modernes, mais la transmission orale du savoir reste dominante.
"Va voir Paul, il connaît bien le sujet" ou "Rajoutes Marie à la réunion, elle maîtrise cette partie-là" sont des phrases qu'on entend quotidiennement.

Pourquoi ce réflexe de l'oral ? La réponse est souvent simple : personne ne fait confiance à la documentation existante. Trop dispersée, mal structurée, obsolète... bref, chaotique.

En travaillant sur les erreurs du DAT, j'en ai tiré la conclusion que le DAT n'est que la partie émergée de l'iceberg : c'est toute notre approche de la documentation qui mérite d'être repensée.

Car au fond, comment créer une documentation en laquelle les équipes auront vraiment confiance ? Comment passer d'une culture de l'oral à une vraie culture de la documentation ?

C'est là qu'intervient une approche qui a révolutionné ma vision : la méthode Diataxis.

Sommaire :

DiataQuoi ?
- Les principes fondamentaux de Diataxis
- La Matrice Diataxis (et son compas)
- À RETENIR
La transformation Diataxis : un exemple concret
Mise en œuvre de Diataxis
- Une application progressive
- Checklist de migration
- Des pièges à éviter
Bénéfices concrets
- Pour les utilisateurs
- Pour les équipes
- Pensez à Mesurer le succès
Des exemples de réussites
Conclusion
Sources et Références

DiataQuoi ?

DIATAXIS (grec ancien : διάταξις, diataxis, « ordre »)

Diataxis, développée par Daniele Procida, propose une méthodologie pour structurer et rédiger la documentation en se fondant sur la compréhension des besoins des utilisateurs.

vous allez voir, c'est très simple à comprendre.

Les principes fondamentaux de Diataxis

Diataxis repose sur le principe que la documentation DOIT répondre aux besoins de son lecteur.

Selon Daniele Procida, il existe quatre catégories de documentation, chacune correspondant à un lecteur cible et un objectif spécifique.
Cette classification implique un contenu et une approche rédactionnelle adaptés à chaque type.

La documentation constitue le principal vecteur de formation des utilisateurs, car elle développe leurs connaissances et leurs compétences.

La méthode s'articule autour de deux axes d'analyse :

L'objectif : acquisition de compétences pratiques ou de connaissances théoriques
L'usage : apprentissage ou application

La Matrice Diataxis (et son compas)

si le contenu décrit des	... et permet à l'utilisateur d' ...	... alors c'est une forme de ...
actions	acquérir des compétences	Tutoriel (tutorial)
actions	appliquer ses compétences	Guide (how-to)
connaissances	acquérir des compétences	Concept (explanation)
connaissances	appliquer ses compétences	Référence (reference)

(J'ai indiqué aussi les termes anglais pour vous repérer dans la doc de Diataxis en anglais)

On aboutit à cette matrice :

Chaque type de documentation possède ses caractéristiques et directives spécifiques.
Pourquoi ?

Introduisons un Concept "Acquisition-Connaissance" ;)

	Que font-ils ?	Répondent à la question	Objectif	Forme
Tutoriel	introduction, éducation	“Pouvez-vous m’apprendre à … ?”	Fournir un apprentissage	Leçon
Guide	guide, procédure	"Comment je fais pour… ?"	Atteindre un but spécifique	Série d'étapes
Concept	explique, clarifie	"Pourquoi… ?"	Eclairer un sujet	Explication didactique
Référence	description, information	"Qu'est-ce que… ?"	Décrire les mécanismes	Description brute

Exemples :

"Je voudrais installer ma première application" ⇾ action & acquérir des compétences ⇾ Tutoriel

"Je voudrais comprendre le choix client/serveur" ⇾ connaissance et acquérir des compétences ⇾ Concept

"Je voudrais configurer finement la base de donnée de mon application" ⇾ action et appliquer des compétences ⇾ Guide

"Je cherche le swagger de l'api de l'application" ⇾ connaissance et appliquer des compétences ⇾ Reference

À RETENIR

Un document = une seule orientation
Chaque type renvoie vers les autres types complémentaires
La documentation forme un réseau cohérent de documents interconnectés

Conséquences pratiques :

Un tutoriel ou guide pratique n'explique pas les concepts sous-jacents
La description d'un concept technique n'inclut pas les détails d'installation
La documentation devient une structure cohérente de documents interconnectés

La transformation Diataxis : un exemple concret

AVANT : Documentation classique

📄 "Documentation Application"
- Présentation
- Installation
- Architecture
- Manuel utilisateur
- Guide développeur
- Guide administrateur
- API
- Exploitation

APRÈS : Documentation Diataxis

📚 Documentation structurée
├── 👤 Utilisateur métier
│   ├── 🎓 Tutoriels
│   │   ├── "Premiers pas sur l'application"
│   │   └── "Créer votre premier dossier"
│   ├── 📖 Guides pratiques
│   │   ├── "Gestion des profils"
│   │   ├── "Import de données"
│   │   └── "Tableaux de bord"
│   ├── 💡 Concepts
│   │   ├── "Vue d'ensemble"
│   │   └── "Processus métier"
│   └── 📚 Référence
│       ├── "Guide des écrans"
│       └── "Liste des raccourcis"
│
├── 🛠 Développeur
│   ├── 🎓 Tutoriels
│   │   ├── "Setup environnement"
│   │   └── "Première feature"
│   ├── 📖 Guides pratiques
│   │   ├── "Tests unitaires"
│   │   ├── "Debug local"
│   │   └── "CI/CD"
│   ├── 💡 Concepts
│   │   ├── "Architecture logiciel"
│   │   └── "Design patterns"
│   └── 📚 Référence
│       ├── "API Reference"
│       └── "Code style"
│
└── 🔧 Ops
    ├── 🎓 Tutoriels
    │   ├── "Premier déploiement"
    │   └── "Setup monitoring"
    ├── 📖 Guides pratiques
    │   ├── "Scalabilité"
    │   ├── "Backup/Restore"
    │   └── "Incident management"
    ├── 💡 Concepts
    │   ├── "Infrastructure"
    │   └── "Sécurité"
    └── 📚 Référence
        ├── "Configuration"
        └── "Métriques"

Mise en œuvre de Diataxis

Une application progressive

Pour débuter, consultez le site Diataxis (en anglais).
La documentation, concise et structurée, comprend 14 pages réparties en deux sections :

Pour chaque forme de documentation, vous retrouverez :

le but
les pièges à éviter
des principes à appliquer dans votre rédaction
le langage à employer

Checklist de migration

Je vous propose une petite check-list de migration pour débuter, je la développerais plus dans le guide de migration du DAT (qui arrive, qui arrive).

Audit de l'existant
- Listez tous vos documents actuels
- Identifiez leur usage principal
Catégorisation
- Classez chaque document selon la matrice
- Identifiez les chevauchements
Plan d'action
- Définissez les priorités
- Établissez un calendrier
- Commencez petit, itérez souvent

Des pièges à éviter

❌ Ne pas faire

Mélanger tutoriel et référence technique
Créer une doc "one size fits all"
Négliger les liens entre documents

✅ Bonnes pratiques par type

Tutoriels

Montrer le résultat final attendu
Découper en étapes de 5-10 minutes
Inclure des captures d'écran
Tester sur environnement vierge

Guides

Un objectif = un guide
Lister les prérequis
Proposer des alternatives
Anticiper les erreurs

Concepts

Utiliser des analogies
Inclure des schémas
Expliquer le "pourquoi"
Lier aux concepts connexes

Référence

Structure cohérente
Exhaustivité
Exemples pratiques
Mise à jour régulière

Bénéfices concrets

Appliquer cette méthode est positive autant pour les utilisateur que pour les équipes.

Pour les utilisateurs

Navigation intuitive
Apprentissage progressif
Autonomie accrue
Satisfaction améliorée

Pour les équipes

Réduction du temps de formation
Moins d'interruptions
Maintenance facilitée
Meilleure collaboration

Pensez à Mesurer le succès

Si on veut que notre documentation soit efficace et serve enfin, il est préférable de mesurer son usage.

Propositions d'indicateurs clés :

Temps moyen de recherche d'information
Taux de consultation
Retours utilisateurs

Des exemples de réussites

Diataxis reste populaire sans être hype. On trouve facilement beaucoup d'entreprises (US majoritairement) qui l'ont mis en oeuvre pour leurs produits.

Des entreprises de référence utilisent Diataxis :

OpenStack : docs.openstack.org/charm-guide/latest/
Ubuntu : ubuntu.com/core/docs
Cloudflare : developers.cloudflare.com
PostgREST : postgrest.org/en/v12/
NumPy : numpy.org/devdocs/dev/index.html

Et voici un REX sur une refonte Diataxis :
Retour d'expérience sur la refonte de la documentation Cloudflare Workers

Conclusion

La force de Diataxis réside dans :

Sa simplicité conceptuelle
Sa flexibilité d'application
Son focus sur les besoins utilisateurs
Sa capacité à évoluer progressivement

Même une application imparfaite de Diataxis améliore significativement la qualité documentaire. La maîtrise vient avec la pratique.

Sources et Références

Site officiel : diataxis.fr Présentations de Daniele Procida :
"What nobody tells you about documentation"
"Python Docs Community Workshop: Introduction to Diataxis"
"Always complete, never finished"

Cet article fait partie du "Advent of Tech 2024 Onepoint", une série d'articles tech publiés par Onepoint pour patienter jusqu'à Noël.
Voir tous les articles du Advent of Tech 2024

Les péchés capitaux du Dossier d'Architecture Technique

Arnaud Gaches — Thu, 05 Dec 2024 08:00:00 +0000

Cet article fait suite à mon précédent article :

Le dossier d'architecture technique, un dinosaure numérique ?

Un Dossier d'Architecture Technique (DAT) reste une documentation complexe à rédiger. L'articulation entre toutes les données techniques que l'on pourrait y déposer est essentielle pour sa lecture.

Les mêmes erreurs reviennent fréquemment dans les DAT que j'ai consulté.
Dans cet article, je voulais vous partager les erreurs majeures identifiées et proposer comment les éviter.

Sommaire :

Créer un document unique
Un DAT séparé de la documentation d'équipe
Une seule personne responsable de son édition
Une rédaction en début de projet ou une absence de révision
Mélanger les niveaux d'architecture
Ne pas utiliser un vocabulaire cohérent
Copier-coller les procédures d'installation
Référencer des documents inaccessibles
Négliger les schémas d'architecture
Conclusion

1. Créer un document unique

Il est surprenant que la majorité des modèles et exemples de DAT proposent un document unique, souvent au format Microsoft Word ou équivalent.

À l'ère de la documentation collaborative, rédiger un volumineux document Word contenant des pages de documentation technique et des copier/coller de contenu de documents existants n'est vraiment pas optimal/idéal.

Si nous avons abandonné les architectures monolithiques pour les applications, pourquoi les conserver pour la documentation ?

Pourquoi est-ce une erreur ?

Cette approche présente plusieurs inconvénients :

Complexité excessive de la hiérarchie des titres
Format inadapté à la lecture sur écran
Déséquilibre entre les sections
Manque de flexibilité pour la spécialisation des parties
Difficulté d'évolution
Recherche d'information complexe
Collaboration limitée

Comment y remédier ?

Heureusement, on a inventé (en 1965) le lien Hypertexte.

Un dossier d'architecture peut et doit constituer une structure de pages et sous-pages.

Privilégiez les liens ou références vers les documents existants plutôt que de dupliquer les informations.

2. Un DAT séparé de la documentation d'équipe

Cette situation est souvent une conséquence directe de l'utilisation d'un document unique.

Pourquoi est-ce une erreur ?

Cette séparation crée une redondance dans l'effort de documentation.

L'équipe travaille avec une documentation collaborative (Wiki, Confluence, etc.) et doit maintenir parallèlement un autre document distinct dont ils n'ont pas l'usage.

Le DAT devrait faire partie intégrante de la documentation des équipes, car il vise principalement à répondre à leurs questions.

Principe : Si une documentation n'a pas d'utilité concrète, ne l'écrivez pas...

Le DAT porte les références techniques décrivant :

Les éléments techniques en place
Leurs relations
Leurs contraintes
Leurs périmètres

L'erreur consiste à le percevoir uniquement comme un livrable pour la mise en production, exigé par les équipes d'exploitation sans valeur ajoutée pour l'équipe solution.

Mais pourquoi est-il réclamé par les équipes d'exploitation ?

Les équipes d'exploitation le demandent car elles ne connaissent pas votre plateforme : elles ont besoin de comprendre les éléments techniques qui la constituent.

Et c'est précisément à cette question que le DAT doit répondre :

"Je ne connais pas la plateforme, comment est-elle construite ?"

Comment y remédier ?

Construisez (et maintenez) le DAT avec deux questions à l'esprit.
"Quels sont les éléments composant ma solution technique ?"
"Quelle est leur configuration pour que la solution fonctionne ?"

Le DAT sert à partager la connaissance :

Pour les nouveaux arrivants dans l'équipe
Pour les intervenants et équipes externes
Pour les anciens eux-mêmes, afin de se remémorer leurs réalisations antérieures

Recommandation : Demandez aux nouveaux membres de l'équipe de mettre à jour et critiquer le DAT.

Cet exercice permet de confronter la documentation à la réalité.

3. Une seule personne responsable de son édition

El Famoso Architecte Omniscient qui voit tout le projet et ses spécificités techniques et mettra le DAT à jour correctement en conséquence n'existe malheureusement pas.

Pourquoi est-ce une erreur ?

L'effort de documentation doit correspondre à la réalisation technique.

Pour documenter efficacement, il est nécessaire d'avoir participé à la réalisation.

Une personne externe devra soit documenter avec des imprécisions, soit solliciter constamment les équipes de réalisation.

Comment y remédier ?

L'architecture et sa documentation sont l'affaire de tous.

L'ensemble des équipes, build et run, participent à l'effort documentaire.

Simon MAURIN vous convaincra mieux que moi en juste 15 minutes :

(youtube) Talk Devvox 2023 "Tous architectes ! (Simon MAURIN)"

4. Une rédaction en début de projet ou une absence de révision

C'est souvent le cas quand le DAT est créé en amont, lors de la phase de cadrage comme document de planification de la future architecture.

Pourquoi est-ce une erreur ?

En amont du projet :

Des questions restent en suspens
Des problématiques demeurent cachées
Les décisions documentées peuvent devenir obsolètes
Les sections concernées restent marquées "à faire"

Ne pas réviser la documentation existante équivaut à l'abandonner.

Comment y remédier ?

Le DAT doit vivre avec la plateforme qu'il décrit, pendant toutes les phases de build ET de run.

Planifiez des révisions régulières de la documentation, incluant le DAT.

Cette approche permet également de traiter la dette documentaire.
Établissez un plan d'action et planifiez-le : c'est un effort sur le long terme.

5. Mélanger les niveaux d'architecture

(petit rappel des niveaux d'architecture existants)

#	Architecture ...	Vue...	Outils
1	...d'entreprise	...stratégique	TOGAF
1bis	...de données	...données	structure et flux de données
2	...fonctionnelle	...métier	Specs fonctionnelles
3	...applicative	...logicielle	diagrammes de classe, etc
4	...technique	...infra & système	...
5	...réseau	...réseau	matrice de flux

L'architecture solution peut englober les niveaux données, fonctionnelle et applicative.

Dans ce cas, l'architecture réseau est généralement intégrée dans l'architecture technique.

Pourquoi est-ce une erreur ?

Mélanger différents concepts ne permet pas d'apporter des réponses précises.

Exemple inadéquat :

"L'architecture est une architecture n-tiers composée d'une webapp Java et d'une base de données Azure Database dans Azure"

Questions sans réponse :

Quel est le moteur de base de données utilisé ?
Dans quel composant s'exécute la webapp ?

Version améliorée :

"L'architecture est une architecture n-tiers composée d'une webapp Java et d'une base de données PostgreSQL.
La webapp Java s'exécute dans une image Docker sur un Azure App Service.
La base de données PostgreSQL est hébergée sur une Azure Database dans Azure."

Comment y remédier ?

Respectez le niveau d'architecture décrit et sa terminologie

Formez les équipes à ces concepts fondamentaux

Chaque responsable doit décrire son périmètre de manière simple et précise

6. Ne pas utiliser un vocabulaire cohérent

C'est une erreur fréquente et compliquée à corriger.

Pourquoi est-ce une erreur ?

La communication est compromise lorsque :

Des termes différents désignent les mêmes composants :

Header / En-tête / Bandeau
Gateway / Passerelle / Proxy / Reverse proxy
Backend / Serveur / API / Services
Machine virtuelle / VM / Instance / Serveur virtuel
Container / Conteneur / Pod / Instance Docker

Des acronymes sont utilisés sans définition :

DR (Disaster Recovery, Data Retention, Design Review, Daily Report)
MS (Microsoft, Microservice, Millisecond)
RC (Release Candidate, Resource Controller, Remote Control)
WAF (Web Application Firewall, Workflow Automation Framework, Windows Authentication Framework, Well Architectured Framework)
BDD (Base de données, Behavior-driven development)
DDD (Domain-driven design, Data display debugger dans gdb)

Des termes génériques utilisés sans autre précision :

Flux (de données, de workflow, RSS, réseau, financier, d'intégration, d'évènement, utilisateur)
Interface (API, graphique, réseau, communication)
Service (microservice, Windows, métier, cloud, support)
Instance (machine virtuelle, classe, base de données, processus)
Client (projet, service, navigateur web, poste utilisateur)
Agent (programme autonome, support technique, monitoring, sécurité)

Bref, tout simplement parce que chacun a son langage et ses codes et qu'il est pertinent de parler le même au sein de la même documentation.

Comment y remédier ?

Établissez un glossaire pour harmoniser la terminologie technique utilisée dans la documentation.

7. Copier-coller les procédures d'installation

Trop souvent, j'ai vu un DAT rempli avec la procédure d'installation.

Pourquoi est-ce une erreur ?

Des pages de captures d'écran avec des instructions basiques :

Compliquent la lecture
Rendent la recherche d'information fastidieuse
Augmentent inutilement le volume du document

Un DAT n'est pas conçu pour héberger les procédures.

Comment y remédier ?

Externalisez les procédures du DAT dans des documents distincts.

Utilisez par exemple les dossiers documentaires spécifiques :

Dossier d'Installation (DIN)
Dossier de Montée de Version (DMV)

8. Référencer des documents inaccessibles

"Retrouvez le document sur Z:\DSI\Procédures-exploitation\DEX-APP.docx"

"Lien https://sharepoint/deleted_user/DAT-APP.docx"

Le drame de trouver ce genre de document, posé sur un espace restreint accessible uniquement par les N2 de l'équipe d'exploitation "mais là ils sont en récupération de l'astreinte HNO de la nuit, faut repasser demain ou faites un ticket".

Ou bien dans le onedrive partagé du prestataire venu faire l'installation de l'outil il y a 3 ans et déjà reparti ...

Pourquoi est-ce une erreur ?

Simplement parce que "Accès refusé" n'est pas l'information que vous recherchez.

Comment y remédier ?

Vérifiez l'accessibilité des documents référencés

Placez chaque solution IT dans son propre espace documentaire

Assurez l'accès aux équipes concernées

Vérifiez régulièrement la validité des liens

9. Négliger les schémas d'architecture

Des mauvais schémas d'architecture, voire pas de schéma du tout.

C'est sans doute l'erreur la plus importante pour la compréhension de la solution :

Un schéma d'architecture fournit :

Une cartographie des composants
Leurs relations
Leurs limites et frontières

De mon expérience, c'est généralement l'information principale recherchée dans un DAT.

Pourquoi est-ce une erreur ?

Un schéma illisible avec :

Une taille excessive
Des liens qui se croisent
Des traits de même couleur
Une mise en page confuse

crée plus de confusion que de clarté.

"Une image vaut 1000 mots."

"Un bon dessin vaut mieux qu'un long discours."

Comment y remédier ?

Faites des schémas !
schéma d'architecture, UML, de base, de classe, de séquence, d'intégration, de déploiement, ...

A tous les niveaux (d'architecture)

A tous les niveaux (de détail)

Conseils pratiques :

Utilisez des outils modernes (draw.io, Lucidchart, Cacoo)
Exploitez les solutions de Diagram-as-Code (Mermaid, PlantUML)
Pour les schémas d'infrastructure Terraform, explorez Brainboard

Conclusion

Voila un petit florilège des erreurs les plus grossières que j'ai rencontré (oui, je les ai toutes eues plusieurs fois).

Ces corrections permettront d'améliorer votre DAT et de réduire votre dette documentaire.

Certaines modifications peuvent s'avérer complexes, impliquant des changements :

Politiques
Organisationnels
De communication
De formation

"Keep it simple" : Optimisez l'utilisation des outils à votre disposition.

Dans les prochains articles, je parlerais de plusieurs armes pour vous aider à remédier à ces erreurs et l'article final vous proposera un guide pour y remédier.

Cet article fait partie du "Advent of Tech 2024 Onepoint", une série d'articles tech publiés par Onepoint pour patienter jusqu'à Noël.
Voir tous les articles du Advent of Tech 2024

Merci de votre lecture !

Le Dossier d'Architecture Technique : un dinosaure numérique ?

Arnaud Gaches — Mon, 02 Dec 2024 07:30:00 +0000

Une question :
"Comment un document conçu il y a quasiment trente ans continue-t-il à être incontournable dans nos projets malgré sa lourdeur et ses anachronismes ?"

Je vous propose d'explorer à travers une série de 5 articles comment faire évoluer le Dossier d'Architecture Technique vers une forme plus adaptée aux enjeux actuels.

Ce premier article a pour but de placer le décor : l'histoire, la nature et le but du DAT.

Petite histoire du DAT

Le Dossier d'Architecture Technique (DAT) en 2024, c'est un peu un dinosaure de l'IT :

Un gros document unique volumineux, poussiéreux dont on ne sait plus trop que faire, mais "il faut un DAT pour mettre en production le projet".

Rajoutons que maintenant, avec l'agilité/le devops ("délivrer souvent"), l'Infra-as-Code, l'automatisation, la scalabilité et le finops, la plateforme évolue plus vite que sa documentation.
Ce qui avant était gravé dans la silice des serveurs physiques est maintenant variabilisé dans un bout de code exécuté quotidiennement.

En plus, l'ancien archi sur le projet est parti sans laisser le fichier visio du schéma d'archi alors on peut plus le mettre à jour.

Et de toute façon, j'ai pas de license Visio

Avec tout ça, la petite motivation de le mettre à jour s'effondre face à la montagne de dette à reprendre.

Du coup, on l'abandonne avec son confrère le DEX (dossier d'exploitation) dans un coin de notre GED (Gestion Electronique des Documents).

À quoi sert un DAT ?

Un dossier d'architecture (DA) est un dossier("document") qui porte les références pour la conception, le développement, le déploiement et la maintenance d'une solution informatique.

(ndlr: je n'aime vraiment pas ce terme "document" que l'on retrouve pourtant trop souvent dans les définitions.)

Le DAT remplit deux fonctions principales :

Documenter et valider formellement l'architecture et les choix techniques d'un projet informatique, pour garantir sa bonne construction et sa maintenance future.
Servir d'engagement ou de protection juridique pour les différents acteurs impliqués dans le projet.

Les plus répandus sont :

Le DAT (Technique)
Le DAG (Générale)

D'autres dossiers se spécialisent sur des aspects architecturaux spécifiques.

Bien que cet article se concentre sur le DAT, les observations s'appliquent à tous les types de Dossiers d'Architecture qui présentent rapidement les mêmes limitations. Le terme DA sera parfois utilisé pour parler plus généralement des Dossiers d'Architecture.

Étape Lexique des acronymes

"Moi, on m'a parlé de DAT ? DAG ? DAS ? DAF ? DAC ? DEX ? DIN ? DMV ?"

Dossier d'architecture…

Technique (DAT) : vue infrastructure, système et réseau
Générale (DAG) : vue entreprise, souvent avec cadre TOGAF
Applicatif / Logiciel (DAL)
Sécurité (DAS)
Data (DAD) : commence à apparaitre
Cloud (DAC)
Dossier d'exploitation (DEX)
Dossier d'installation (DIN)
Dossier de Montée de Version (DMV)

La complexité de maintenir un seul document a vu naitre pratiquement autant de document que de vision d'architecture.

Mais pourquoi un si gros document ?

Le DAT est devenu un document volumineux pour plusieurs raisons historiques et pratiques :

1. Contexte historique

Bonne question : Quand est né le DAT ?

La notion d'architecture informatique émerge véritablement dans les années 1990s.
Une recherche de publications techniques sur l'architecture informatique révèle un premier article en 1964 (concernant l'architecture de l'IBM System/360), suivi d'une croissance continue jusqu'à aujourd'hui.

Le TOGAF (The Open Group Architecture Framework) introduit en 1995 la notion d'aspects de l'architecture (métier, données, applicative, technique) et formalise les concepts et pratiques, dont les DA.
Il se base sur le TAFIM, un concept développé par le Département de la Défence Américain.

Dans les années 1990 en France, de grands projets de structuration des DSI des groupes français démarrent.
Ces DSI se structurent en faisant appel aux premières Sociétés de Services en Ingénierie Informatique (SSII).

Deux éléments spécifiquement français ont influencé les choix :

L'influence de la culture d'ingénieur française
La tradition française (administrative, affaires et ingénierie) privilégiant l'écrit formel

La gestion documentaire existait déjà dans d'autres domaines industriels.
Le TOGAF et ses DAG/DAT ont donc été naturellement adoptés.

2. Aspects juridiques et contractuels

DSI important + contractants (SSII et éditeurs) + contrats aux montants importants = protection contractuelle nécessaire.
Il devient impératif de se protéger juridiquement dans les relations client-fournisseur.

Le DAT devient un document de référence pour :

La base contractuelle en cas de litiges potentiels
Les audits et certifications

3. Culture organisationnelle

La structure hiérarchique des entreprises françaises induit une hiérarchisation similaire au sein des DSI.
La relation client-fournisseur et les engagements contractuels créent une séparation marquée des rôles (MOA/MOE), nécessitant une documentation détaillée.
"Le client maîtrise le métier, la SSII maîtrise la technique."

Tout doit être documenté de manière exhaustive.

4. Contraintes sectorielles

L'entreprise doit respecter différentes contraintes :

Les exigences réglementaires (notamment dans la banque/assurance)
Les besoins de conformité (normes ISO, RGPD, etc.)
La documentation des choix pour les audits de sécurité

Impact

N'oublions pas une certaine culture française de la ~~paperasse~~ "traçabilité des décisions".

Ironiquement, tous ces points vont directement nuire à l'efficacité du document :

Temps considérable requis pour la rédaction et la maintenance
Multiplicité des intervenants devant mettre à jour leur partie de DAT
Risque de dilution ou perte des informations cruciales
Décalage potentiel avec la réalité du projet

Le DAT français par rapport au reste du monde

Non, le DAT n'est pas universel. Les autres pays utilisent des formes différentes de documentation d'architecture.

Petit exercice de comparaison de DAT avec le Technical Design Document (TDD), qui est probablement l'équivalent le plus proche dans le monde anglo-saxon.

Aspect	DAT (France)	TDD (Anglo-saxon)
Structure et Formalisme	Structure normée et standardisée Sections obligatoires Format souvent imposé	Structure souple et adaptable Sections recommandées Format flexible
Contenu et Profondeur	Description exhaustive Inclut aspects gouvernance Documentation détaillée des choix Accent sur la traçabilité	Centré aspects techniques Documentation concise Orienté implémentation Moins d'aspects organisationnels
Cycle de vie	Validation formelle préalable Mises à jour peu fréquentes Document de gouvernance	Évolution continue Mises à jour fréquentes Guide vivant
Usage	Document contractuel Base pour validation/audits Référence officielle	Document de travail Communication technique Support développement
Culture d'entreprise	Culture hiérarchique Gestion formelle Relations client-fournisseur	Culture agile Adaptabilité Focus équipe développement

Ces différences reflètent des approches culturelles distinctes de la gestion de projet et de la documentation technique :

Le DAT s'inscrit dans une approche formelle, exhaustive et hiérarchique, servant de document contractuel et de gouvernance,
Le TDD adopte une démarche plus souple, privilégiant l'efficacité opérationnelle et l'agilité.

Différence clé avec le DAT :

Le DAT souffre souvent d'une rigidité excessive qui freine les mises à jour
Le TDD souffre plutôt d'un manque de rigueur qui peut créer du flou

Conclusion

En 2024, le DAT reste manifestement un vestige du passé.
Malgré les révolutions technologiques successives, la documentation n'a pas évolué en conséquence.
Peu de publications actuelles parlent de documentation et proposent des solutions pour transformer cette situation.

Les publications existantes se concentrent principalement sur "quel contenu inclure", sans réellement aborder la question "comment le rédiger ?"
Les évolutions technologiques récentes offrent pourtant de nouvelles possibilités et je suis convaincu que l'on peut faire autrement.

Pour le prochain article, on parlera des erreurs les plus fréquentes.

Cet article fait partie du "Advent of Tech 2024 Onepoint", une série d'articles tech publiés par Onepoint pour patienter jusqu'à Noël.
Voir tous les articles du Advent of Tech 2024

Merci pour votre lecture.

Passer sa certification Google Cloud Professional (Cloud Architect) : L'entrainement à la certification

Arnaud Gaches — Tue, 15 Oct 2024 16:36:16 +0000

Explorer et approfondir les différents services

La formation (surtout payante) reste trop souvent superficielle sur les différents services.
Faire des labs permet de rendre la théorie plus concrête.

Il existe de nombreuses ressources et labs payants, je ne m’attarderais pas dessus. Je me concentre sur les ressources de Google disponibles gratuitement :

Carte des services Google

→ Google Cheat Sheet
Excellente antisèche avec les Sketchnotes.
Les tuiles sont cliquables et fournissent une petite description ainsi qu'un lien vers la documentation Google.
Et on apprécie la recherche qui permet de trouver rapidement un service.

Approche sur un sujet

→ Sketchnotes The Cloud Girl
Un schéma vaut parfois 1000 mots

Perfectionnement sur un sujet

→ Documentation Google
Pas le choix : RTFM

Entrainement sur un sujet

→ Codelabs Google

Questions sur un sujet

→ Learning Forums Google

TIPS: Doc Google et Google Skills Boost
La doc Google et la doc de training Google Skills Boost sont liés sur tout ce qui parait être tutorial et exemples.
Si vous n’avez pas accès aux Skills Boost, vous pourrez vous retrouver bloqué sur l’accès à certains labs

L’entrainement à la certification

Comment répondre aux questions des QCM ?

Bien lire la question
Eliminer les réponses invalidées par certains éléments de la question (généralement au moins 2)
Comprendre le besoin de la question pour déterminer la réponse la plus adaptée
Si 2 réponses conviennent, la plus adaptée sera la plus simple et la moins chère

Que retenir des Use Case ?

Pas besoin du "par coeur".
(re)lisez-les plusieurs fois pour être bien familiés avec ces use case.
Réfléchissez aux solutions que vous prendriez et pourquoi.
Ce sont de bons cas d’école pour faire des kata d’architecture.

Les examens blancs

Pour vous entrainer à passer l’examen de la certification, vous avez plusieurs choix :
Je fais l’impasse sur les QCM générés par IA : ils sont intéressants mais ne représentent pas du tout les questions de QCM que vous aurez.

Une proposition gratuite/payante : Whizlabs
(vous avez un test gratuit possible en plus de ceux payants)
Mon avis : je suis pas très fan des questions trouvées dans ces examens blancs, et notamment des réponses.
Je préfère personnellement ExamTopics.

ExamTopics

Un dernier site à conseiller pour s’entrainer sur les questions directement.
Ce site n’est pas exactement un site d’examens blancs.
Il propose des centaines de questions d’entrainement qui ressemblent à celles de l’examen (270+ pour le Cloud Architect).
Le fonctionnement est particulier :
Les réponses proposées ne sont pas toujours bonnes.
MAIS vous avez les commentaires de la communauté avec les liens vers les docs, très enrichissant et intéressant.

Passer sa certification Google Cloud Professional (Cloud Architect) : Se former

Arnaud Gaches — Tue, 15 Oct 2024 16:36:05 +0000

Se former

Préparer une telle certification demande un investissement en temps et en énergie pour se former.

Le parcours de formation vous permettra de définir les sujets à aborder, estimer l’effort nécessaire et les organiser dans votre planning.

Réserver la date de passage de votre certification dès à présent
Réservez et posez le créneau d’examen une fois que vous aurez défini votre plan et estimé le temps d’étude.
Une deadline apporte plus d’engagement et donc de motivation.

Autoformation ou formation payante ?

Autoformation

Je trouve que l’auto-formation a un certain intérêt par rapport aux formations payantes :

Aucune formation payante n’est suffisante pour passer directement la certification sans travailler derrière.

L’auto-formation permet d’y aller à son rythme et de pouvoir adapter le temps passé aux sujets selon leur complexité.

(voir chapitre Explorer et approfondir les différents services)

Pour ses partenaires, Google met à disposition des parcours de formation (Learning path) Google Cloud Skills Boost / Qwiklabs

Malheureusement, à l’opposé d’autres clouds providers, les learning paths de Google sont payants (29$/mois).

Rq: Si votre société est partenaire, vous avez déjà probablement un accès à cette documentation.

Learning Patch Google

Vous retrouverez tous les Paths Google ici :

https://partner.cloudskillsboost.google/

Path Professional Cloud Architect :

https://partner.cloudskillsboost.google/paths/77

Path en 3 étapes :

Cloud Digital Leader : https://partner.cloudskillsboost.google/paths/75

Associate Cloud Engineer : https://partner.cloudskillsboost.google/paths/69

Professional Architect : https://partner.cloudskillsboost.google/paths/117

Passerelle pour AWS et AZURE

Google Cloud Infrastructure for Azure professionals : https://partner.cloudskillsboost.google/paths/96
Google Cloud Infrastructure for AWS professionals : https://partner.cloudskillsboost.google/paths/95

Mentorat par un sachant

Ca parait une évidence mais avoir une personne déjà certifiée qui peut nous mentorer et à qui on peut adresser nos questions est un énorme avantage.

ça reste vraiment un bénéfice important par rapport une simple auto-formation doc+labs.

Formations (payantes)

Il existe de nombreuses formations disponibles en ligne pour se préparer à cette certification, la plupart étant payantes.

Assurez-vous de l’adéquation entre le contenu de la formation et le contenu de la certification !

Je vous liste ici 2 formations plutôt reconnues :

Udemy : https://www.udemy.com/course/google-cloud-professional-architect-get-certified/

Coursera : https://www.coursera.org/professional-certificates/cloud-engineering-gcp

Créer son parcours de formation

Le plus simple consiste à suivre un parcours complet existant qui couvrira tous les domaines et piocher parmi ceux que vous ne connaissez pas, et si vous débutez, facile, vous ferez tout ! :)

Utiliser les termes anglais !
Même si la documentation est en français, je trouve préférable de s’habituer immédiatement aux termes anglais: plus de documentation, plus de références et de ressources, et l’examen de certification sera en anglais.

Tous les composants GCP que je mentionnerais le seront avec leur nom anglais.

Le programme aborde les grands domaines suivants :

(ils ont été extraits des Learning Path de Google)

Code Infra

console google, compute, disks, network.

Core Services

IAM, Storage & Database, Resources management, Resources monitoring.

Scaling and Automation

VPC interconnection, Load Balancing & Autoscaling, Infrastructure Automation.

SRE : Design & Process

Defining service (SLA/SLO/SLI), Microservice, Devops Automation, Choosing Storage solutions, Google Cloud & Hybrid, Deploy Apps to GCP, Designing Reliable Systems, Security, Maintenance & Monitoring.

Google Kubernetes Engine

Containers & Kube, Kube Architecture, Kube operations.

Logging and Monitoring

Cloud Operations Suite, Monitoring critical systems, Alerting Policies, Advanced Logging and Analysis, Audit Logs.

Load Balancing

Data ML

Vertex AI, Dataprep, Dataflow, Dataproc, Cloud Natural Language API, Speech-to-Text API, Video Intelligence.

Build & Terraform

Using Terraform in Google

Network

Set Up a Google Cloud Network (Hybridation : Anthos).

Finops

Optimize Costs for GKE, Optimize Costs for GCP.

Forem: Arnaud Gaches

ça ressemble à quoi, mon setup Claude Code ?

1. La configuration préalable du poste

2. Quelle configuration de Claude a été mise en place et où ?

L'anatomie du dossier ~/.claude/ global

settings.json : déterministe vs inférentiel

Hooks globaux

MCP globaux

Skills et Plugins globales

CLAUDE.md vs /commandes vs agents

3. Agent schedulé

4. Repo par repo

Blog éditorial

Lab Scaleway / infra

Thinking — le 2e brain perso

5. L'heure du bilan

Ce qui fonctionne bien

Ce qui m'irrite encore

Ce qui manque encore

6. Conclusion

Vous avez raté la vague MCP ? C'est pas grave.

Trois actes, trois interfaces

L'argument n°1

Le choix dépend du modèle

L'heuristique du terrain

L'industrialisation : pas si simple

L'argument enterprise

Ce débat ne se pose que quand on a le choix

La vraie question

IA #DevTools #CLI #MCP #AgentsIA #PlatformEngineering

OpenAI a perdu 22 points en 12 mois : Le marché IA se recompose.

1. OpenAI : l'érosion pas si silencieuse

2. Copilot, un parfum de Windows Me

3. Mon pari : le marché IA de 2027 en 4 piliers

Pilier 1 — Google/Gemini : le généraliste dominant

Pilier 2 — Anthropic/Claude : le premium pour les pros

Pilier 3 — L'IA locale

Pilier 4 — L'inconnue chinoise

Que deviennent les autres sociétés d'IA ?

4. Et donc, on fait quoi ?

IA #OpenAI #Microsoft #Copilot #Google #Anthropic #Strategie #Dev

Mes sources

DAT as Code : automatiser la documentation technique avec l'IA

Introduction

La découverte : templates + prompts

Le problème : 3 outils à synchroniser

La solution : MCP (Model Context Protocol)

Setup

Itération 1 : créer la documentation

Itération 2 : itératif

Itération 3 : doc d'exploitation

Itération 4 : publication dans Confluence

Itération 5 : GitHub Actions (en cours)

Premier test : tout régénérer

Deuxième test : détection d'écarts

Bilan

Ce que ça donne

Les limites

Le mot de la fin : Assistant, pas remplaçant

Arrêtez de demander au LLM si c'est bien. Demandez-lui ce qui cloche.

Introduction : La boucle de l'enfer

Le problème : le biais de complaisance des LLM

La "sycophancy" (complaisance) : un défaut documenté

Le coupable : le réentraînement (Reinforcement Learning from Human Feedback - RLHF)

Les conséquences concrètes critiques

La solution : les personas négatifs

Pourquoi ça marche ?

Contrainte de l'adversaire

Simuler l'adversité avant qu'elle arrive

Remplacement d'un lecteur externe

Limites et bonnes pratiques

1. Faux positifs : la règle des "2+ personas"

2. Manque de contexte

3. Diversifier les angles de vue

Next step : Passez à l'offensive

Votre boîte à outils pour commencer

Mode d'emploi express (15 min chrono)

La preuve par l'exemple : le crash-test de cet article

Le mot de la fin

Sources

L'anatomie du dossier `~/.claude/` global

CLAUDE.md vs `/commandes` vs agents