Fondamentaux de la documentation ops¶

Comprendre pourquoi documenter, quels types de documents produire, et comment entretenir une documentation qui reste utile dans le temps.

Pourquoi documenter¶

Une infrastructure non documentee est une infrastructure fragile. La documentation ops répond a plusieurs besoins critiques :

Accès 24/7 — En astreinte a 3h du matin, personne ne se souvient de tout. Une documentation accessible et fiable réduit drastiquement le temps de résolution des incidents.

Onboarding — Un nouvel arrivant doit pouvoir devenir autonome sans mobiliser l'équipe en continu. La documentation remplacé les transmissions orales qui s'evaporent.

Bus factor — Si une seule personne connait le fonctionnement d'un système, l'équipe est exposee. Documenter distribué la connaissance et réduit le risque de perte de compétences critiques.

Trace des décisions — Pourquoi ce choix technologique ? Pourquoi cette configuration spécifique ? Sans trace écrite, l'équipe refait les mêmes debats et reproduit les mêmes erreurs.

Types de documentation ops¶

Chaque type de document a un objectif, une audience et un rythme de mise à jour spécifiques.

Documentation vivante vs obsolète¶

Une documentation obsolète n'est pas neutre : elle induit en erreur et crée une fausse confiance. Les signes d'une documentation morte sont reconnaissables :

• Dates de mise à jour vieilles de plus d'un an sans changement visible dans les systèmes
• Références a des serveurs, outils ou processus qui n'existent plus
• Captures d'écran d'interfaces qui ont change
• Procédures qui ne correspondent plus à la réalité (on le decouvre en incident)
• Personne ne sait qui est responsable de la page

Maintenir la documentation à jour¶

Quelques pratiques qui fonctionnent :

• Lier la mise à jour de la documentation aux tickets de changement (définition of done)
• Assigner un owner à chaque section ou document
• Planifier une revue trimestrielle et l'inscrire au calendrier de l'équipe
• Utiliser des dates de peremption explicites sur les documents sensibles au temps

Culture de l'écrit¶

La documentation ne se maintient pas par obligation mais par culture. Quand l'équipe comprend que la doc lui profite directement, le cercle devient vertueux.

graph LR
    A["Ecrire la doc"] --> B["Utiliser la doc"]
    B --> C["Corriger et enrichir"]
    C --> D["Doc plus fiable"]
    D --> A

Obstacles courants et réponses¶

Principes fondateurs¶

• Docs as code : stocker la documentation dans Git, la versionner, la réviser comme du code
• Progressive disclosure : du plus simple au plus détaillé, ne pas tout mettre au même niveau
• Single source of truth : éviter la duplication — une info a un seul endroit, mis à jour une seule fois
• Audience first : écrire pour le lecteur en situation de stress, pas pour le redacteur en mode réflexion