馃巵 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
- 2. Mettre en place une gouvernance documentaire
- 3. Mise en 艙uvre
- 4. Les aides pour cette migration
- 5. Mesures et retours d'exp茅rience
- 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
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
Top comments (0)