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

🎁 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 :

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

Migration progressive

La migration doit être progressive et planifiée :

1. Commencer par les documents les plus consultés
2. Migrer en parallèle de l'existant
3. Valider avec les utilisateurs
4. 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 :

1. Partager et intégrer des documents dans des structures complexes
2. Documenter en parallèle du développement (code applicatif ou infrastructure)
3. Versionner et publier selon des stratégies documentaires élaborées
4. 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 :

1. Fournir les liens vers les références techniques
2. Générer une documentation à partir des éléments existants
3. 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