- Description
- Longue allée de rayonnages de magasin de bibliothèque, remplis de volumes reliés.
- Source
- Chevsapher · page d’origine
- Licence
- CC0 Domaine public
Documentation et transmission du savoir
Ce thème mesure la résilience de l'équipe à la perte ou à l'arrivée d'une personne : ce qui est su par tous, trouvé en quelques minutes, et maintenu à jour parce que la documentation vit…
En bref
Ce thème mesure la résilience de l'équipe à la perte ou à l'arrivée d'une personne : ce qui est su par tous, trouvé en quelques minutes, et maintenu à jour parce que la documentation vit avec le code. La promesse n'est pas « beaucoup de pages » mais « un nouvel arrivant est productif vite, et un départ ne crée pas de trou ». Pour la documentation propre aux données (catalogue, lineage), voir Data 12.
Niveau : 🟢→🔴 · Code thème : DOC (matrice DL)
Pourquoi ce thème#
Le facteur camion (bus factor) est le nombre de personnes dont le départ paralyserait un composant. Quand il vaut 1, tout le monde le sait, personne ne le dit. La documentation ne remplace pas la transmission orale, mais elle la rend asynchrone, consultable et durable. Elle a aussi un ennemi : la péremption. Une documentation fausse est pire qu'une absence, car elle crée de la confiance injustifiée.
Le cadre Diátaxis distingue quatre natures de documents que l'on confond souvent : tutoriels (apprendre), guides pratiques (accomplir une tâche), références (consulter), explications (comprendre le pourquoi). Un seul document ne peut pas tout faire à la fois. La documentation la plus durable est adjacente au code et générée quand c'est possible (références d'interfaces, schémas de base, propriétés étendues SQL), pour éviter la double saisie qui dérive.
Ce que mesure le thème#
- Axe : de « le savoir est dans les têtes » à « le savoir est partagé, vérifié et utilisé ».
- Indicateurs clés : facteur camion par composant ; délai d'autonomie d'un nouvel arrivant ; ancienneté médiane des pages ; taux de questions récurrentes.
- Unité : nombre de personnes ; jours ; mois ; %.
Tableau des cinq niveaux#
| Niveau | Nom court | Promesse | Indicateur type (ordre de grandeur) |
|---|---|---|---|
| 1 | Oral | Le savoir est disponible tant que les personnes le sont. | Facteur camion = 1 sur des composants clés |
| 2 | Écrit | Un nouvel arrivant trouve de quoi démarrer et sait à qui demander. | Pages d'accueil et d'installation ; autonomie ≈ 4-8 sem. |
| 3 | Maintenu | La documentation est trouvée en moins de 5 minutes et sa fraîcheur est connue. | Responsable par page ; péremption < 12 mois |
| 4 | Vivant | La documentation est modifiée avec le code, et ce qui peut être généré l'est. | Vérification en revue ; références générées ; autonomie ≈ 2 sem. |
| 5 | Partagé | Tout composant a au moins trois personnes capables de le faire évoluer, et le savoir circule sans réunion. | Facteur camion ≥ 3 partout ; autonomie < 1 sem. |
Jalons par niveau#
| ID | Jalon | Preuve vérifiable |
|---|---|---|
| DL-DOC-1.1 | Un point d'entrée unique renvoie vers le reste (accueil du dépôt, page d'équipe) | Lien connu de tous |
| DL-DOC-1.2 | Les procédures d'installation et de build sont écrites | Suivie par un tiers : réussite |
| DL-DOC-1.3 | Les experts de chaque composant sont identifiés | Tableau composant → personnes |
| DL-DOC-2.1 | Un guide d'arrivée liste accès, outils, premières tâches | Utilisé par les 3 dernières arrivées |
| DL-DOC-2.2 | L'architecture est décrite à gros grain (voir 01) | Schéma daté |
| DL-DOC-2.3 | Les interfaces (API, vues, échanges de fichiers) ont une référence | Référence consultable |
| DL-DOC-2.4 | Les procédures d'exploitation (démarrer, reprendre, restaurer) sont écrites | Rejouées une fois par un non-auteur |
| DL-DOC-3.1 | Chaque page porte propriétaire et date de dernière vérification | Métadonnées présentes sur ≥ 90 % |
| DL-DOC-3.2 | Un moteur de recherche couvre la documentation ; les questions fréquentes sont recensées | Test : 5 questions retrouvées en < 5 min |
| DL-DOC-3.3 | Les quatre natures (tutoriel, guide, référence, explication) sont distinguées | Structure du site |
| DL-DOC-3.4 | Les décisions importantes sont conservées avec leur contexte (ADR) | Journal de décisions |
| DL-DOC-3.5 | Le facteur camion est évalué par composant et suivi | Tableau mis à jour trimestriellement |
| DL-DOC-4.1 | La documentation est dans le dépôt, versionnée avec le code et revue dans la même demande de fusion | Revue de 10 PR : doc mise à jour quand nécessaire |
| DL-DOC-4.2 | Les références (schémas, API, propriétés SQL) sont générées depuis la source | Génération en pipeline |
| DL-DOC-4.3 | Les liens et exemples de code de la documentation sont testés automatiquement | Vérification en CI |
| DL-DOC-4.4 | La documentation est publiée à chaque livraison avec la version correspondante | Site par version |
| DL-DOC-4.5 | Le délai d'autonomie d'un arrivant est mesuré et < 2-3 semaines | Mesure sur les 3 dernières arrivées |
| DL-DOC-5.1 | Facteur camion ≥ 3 sur chaque composant critique | Matrice de compétences |
| DL-DOC-5.2 | Des pratiques de transmission régulières (binômage, rotations, revues croisées) sont institutionnalisées | Calendrier et traces |
| DL-DOC-5.3 | Un départ simulé (exercice « et si X partait ? ») ne révèle aucun trou critique | Compte rendu d'exercice |
| DL-DOC-5.4 | Les questions récurrentes deviennent de la documentation ou de l'automatisation en < 1 mois | Suivi des questions récurrentes |
Lecture détaillée par niveau#
🟢 Niveau 1 — Oral#
- Signes : « demande à untel » ; installation fantôme ; réponses divergentes.
- Gain : zéro coût d'écriture.
- Ne garantit pas : la continuité si un expert part ou tombe malade.
- Difficulté : 1/5 · Effort : 1/5.
🟢 Niveau 2 — Écrit#
- Signes : un guide d'arrivée, un schéma, des procédures d'exploitation.
- Gain : première autonomie des arrivants.
- Ne garantit pas : la fraîcheur ; la plupart des documentations de ce niveau périment en un an.
- Difficulté : 2/5 · Effort : 2/5.
🟡 Niveau 3 — Maintenu#
- Signes : chaque page a un propriétaire et une date de vérification ; la recherche fonctionne ; le pourquoi (décisions) est conservé à côté du comment.
- Gain : on fait confiance à la documentation, donc on la consulte, donc on la corrige.
- Ne garantit pas : qu'elle suive le rythme du code.
- Difficulté : 3/5 · Effort : 3/5.
🔴 Niveau 4 — Vivant#
- Signes : « la doc fait partie de la définition de terminé » ; la revue refuse un changement d'interface sans mise à jour de la référence ; ce qui est dérivable du code ou de la base (schémas, dictionnaire, propriétés étendues) est généré.
- Gain : la fraîcheur devient un effet de bord du travail courant.
- Ne garantit pas : la transmission tacite (le jugement, l'intuition du métier).
- Difficulté : 4/5 · Effort : 4/5.
🔴 Niveau 5 — Partagé#
- Signes : rotations, binômage, revues croisées ; le facteur camion est ≥ 3 ; un exercice de départ simulé ne trouve pas de trou.
- Gain : résilience organisationnelle.
- Ne garantit pas : l'efficacité — trop de redondance de compétences a un coût, à calibrer sur la criticité.
- Difficulté : 5/5 · Effort : 4/5.
Atteinte partielle et notation#
Appliquez la règle de notation.
- 0,5 sur DL-DOC-4.2 : références générées pour la base, rédigées à la main pour les API.
- 0,5 sur DL-DOC-5.1 : facteur camion ≥ 3 sur la moitié des composants critiques.
- Un 5 partiel : rotations annuelles réelles mais aucun exercice de départ simulé.
Wiki cimetière. Symptôme : 600 pages, 80 % périmées, personne ne sait lesquelles. Cause : aucune propriété ni date. Remède : archiver ce qui n'a pas de propriétaire ; marquer la date de vérification.
Documentation d'une seule nature. Symptôme : une page de 40 écrans qui est tout à la fois. Cause : on ignore la distinction tutoriel/guide/référence/explication. Remède : scinder.
Le meilleur test de documentation : faites réaliser une tâche réelle (installer, déployer une correction) par quelqu'un qui n'a jamais vu le composant, sans l'aider. Chaque question est un défaut de documentation.
Résumer, rédiger une première version, répondre aux questions sur la base documentaire : gain 4/5, risque 3/5 (réponses plausibles mais périmées ou inventées). Garde-fou : l'IA cite ses sources internes et ne publie rien sans relecture d'un propriétaire.
Mesurer le nombre de pages produit du volume ; mesurez le délai d'autonomie et la fraîcheur.
Passer au niveau suivant#
Moyens possibles (facultatifs)
- 1 → 2 : un guide d'arrivée écrit par le dernier arrivé (c'est lui qui connaît les trous).
- 2 → 3 : propriétaire et date par page, archivage, ADR.
- 3 → 4 : la documentation dans le dépôt, génération des références, vérification des liens.
- 4 → 5 : rotations, exercice de départ simulé, matrice de compétences.
Voir aussi#
- Voisins : 01 Architecture · 09 Dette technique · 12 Expérience développeur · 06 Déploiement.
- Autres matrices : Data — métadonnées, lineage et documentation · Projet — équipe et collaboration · Projet — amélioration continue.
- Pratique : Git en profondeur · IA et outils · fondamentaux de la conduite de projet.
- Glossaire · Notation.
✻ Rédigé par Claude Sonnet 5.5
