L'importance de documenter
Mise à jour :
La documentation n’est pas un bonus. C’est un livrable au même titre que le code ou l’infrastructure. Une équipe qui ne documente pas accumule une dette invisible : procédures opaques, connaissances dans la tête d’une seule personne, incidents plus longs à résoudre. Documenter, c’est rendre le savoir explicite, partageable et vérifiable. C’est aussi se protéger contre le départ d’un collègue, l’oubli ou l’urgence.
Pourquoi documenter en DevOps
Réduire l’impact des incidents
Quand un système tombe en panne à 3h du matin, personne n’a envie de fouiller dans sa mémoire ou d’appeler un collègue. Une procédure écrite (runbook) permet d’agir vite, même sans tout comprendre. Sans documentation, chaque incident devient une enquête. Avec documentation, c’est une checklist.
Assurer la continuité
Les équipes changent. Les gens partent, arrivent, changent de poste. Si le savoir est uniquement dans la tête des anciens, il disparaît avec eux. La documentation garantit que l’équipe peut continuer à fonctionner même après des départs.
Améliorer la qualité
Documenter force à clarifier. Quand on écrit une procédure, on découvre souvent des incohérences ou des étapes manquantes. La documentation est un outil de qualité, pas seulement d’archivage.
Faciliter le transfert de connaissance
Un nouveau dans l’équipe ne devrait pas avoir besoin de poser cinquante questions pour comprendre comment déployer ou accéder aux logs. La documentation lui donne l’autonomie d’apprendre par lui-même.
Ce qu’il faut documenter (le minimum vital)
Tout documenter est irréaliste. Voici les éléments essentiels :
- Runbooks : procédures de réponse aux incidents courants (service down, saturation disque, etc.)
- Procédures de déploiement : comment livrer une nouvelle version, rollback si besoin
- Architecture : schéma des composants, flux de données, dépendances entre services
- Dépendances externes : APIs tierces, services cloud, bases de données partagées
- Accès et permissions : qui a accès à quoi, comment demander un accès
- Limites connues : ce que le système ne supporte pas, seuils de charge, contraintes
- RTO/RPO : temps de reprise acceptable, point de récupération (si pertinent pour votre contexte)
Les qualités d’une bonne documentation
Simple
Accessible à tous, sans jargon inutile. Si un nouveau peut la comprendre, c’est bon signe.
Cohérente
Les documents se réfèrent les uns aux autres. Pas de contradictions entre deux pages.
Datée et versionnée
Chaque document indique quand il a été mis à jour et pour quelle version du système. Une documentation sans date est suspecte.
Vérifiable
Les procédures peuvent être testées. Si une documentation dit “exécuter cette commande”, quelqu’un doit pouvoir la valider.
Maintenable
Facile à mettre à jour. Si modifier un document demande trois jours, personne ne le fera.
Scénarios concrets
Scénario 1 : Incident en production sans runbook
Situation : Le service de paiement tombe à 22h. L’ingénieur d’astreinte n’a jamais travaillé sur ce composant.
Sans documentation :
- Il cherche dans les logs, ne comprend pas les erreurs
- Il appelle un collègue qui connaît le système — mais il est injoignable
- Il tente des redémarrages à l’aveugle, aggrave le problème
- Le service est rétabli après 3 heures, avec perte de transactions
Avec un runbook :
- Il ouvre le runbook “Service paiement down”
- Il suit les étapes : vérifier le certificat, relancer le pool de connexions, valider
- Le service est rétabli en 20 minutes
Leçon : le runbook n’a pas besoin d’être parfait. Il doit juste exister et couvrir les cas courants.
Scénario 2 : Arrivée d’un nouveau
Situation : Une développeuse rejoint l’équipe. Elle doit être opérationnelle rapidement.
Sans documentation :
- Elle pose des questions à tout le monde, interrompt le travail des autres
- Elle découvre les accès par hasard, perd du temps
- Après trois semaines, elle a encore des zones d’ombre
Avec documentation :
- Elle lit le guide d’onboarding, obtient ses accès en autonomie
- Elle consulte l’architecture pour comprendre les flux
- Après une semaine, elle peut contribuer au code et aux déploiements
Leçon : le temps investi dans la documentation se récupère à chaque nouvel arrivant.
Erreurs fréquentes (et comment les éviter)
| Erreur | Conséquence | Comment l’éviter |
|---|---|---|
| Confondre commentaires de code et documentation | Le code explique le “comment”, pas le “pourquoi” ni le contexte métier | Séparer la doc technique (runbooks, architecture) des commentaires inline |
| Documentation jamais testée | Les procédures ne marchent pas quand on en a besoin | Faire valider chaque runbook par quelqu’un qui n’a pas écrit le code |
| Documentation orpheline | Personne ne sait qui maintient quoi | Attribuer un propriétaire à chaque document |
| Documentation obsolète | Les équipes perdent confiance et arrêtent de consulter | Intégrer la mise à jour dans la “definition of done” |
| Pas de gouvernance | Doublons, contradictions, formats différents | Définir un responsable documentation et des règles minimales |
Une gouvernance légère qui marche
Attribuer un propriétaire
Chaque document a un responsable identifié. Ce n’est pas forcément celui qui l’écrit, mais celui qui s’assure qu’il reste à jour.
Intégrer dans la definition of done
Une fonctionnalité n’est pas terminée tant que la documentation associée n’est pas mise à jour. C’est une règle d’équipe, pas une option.
Faire des revues
Comme le code, la documentation se relit. Une deuxième paire d’yeux attrape les ambiguïtés et les erreurs.
Définir un rythme de mise à jour
Une revue trimestrielle des documents critiques suffit souvent. L’important est d’avoir un rythme, pas forcément une fréquence élevée.
Ce que documenter n’est pas
- Ce n’est pas écrire un roman : des phrases courtes, des listes, des schémas. Pas de littérature.
- Ce n’est pas uniquement des screenshots : les captures d’écran deviennent obsolètes à chaque changement d’interface. Elles complètent le texte, elles ne le remplacent pas.
- Ce n’est pas un PDF figé : la documentation vit avec le système. Un document qu’on ne peut pas modifier facilement est un document mort.
- Ce n’est pas le travail d’une seule personne : toute l’équipe contribue. La documentation est collective.
- Ce n’est pas un exercice de style : on écrit pour être compris, pas pour impressionner.
À retenir
- La documentation est un livrable, pas un bonus optionnel
- Documenter le minimum vital (runbooks, architecture, accès) suffit pour commencer
- Une bonne documentation est simple, datée, testable et maintenable
- Chaque document doit avoir un propriétaire identifié
- Le temps investi se récupère à chaque incident et chaque nouvel arrivant
Liens utiles
- Qu’est-ce que DevOps ? — comprendre la culture dans laquelle s’inscrit la documentation
- Glossaire DevOps — définitions des termes courants
- Bonnes pratiques DevOps — autres pratiques complémentaires