Documentation opérationnelle : structurer pour retrouver

Vous êtes-vous déjà retrouvé à 2 heures du matin face à un serveur en panne, à vous demander : “Qui a configuré ce truc ? Où sont les identifiants ? C’est quoi déjà la procédure de redémarrage ?” Si oui, vous avez vécu le cauchemar d’une documentation absente ou introuvable.

La documentation opérationnelle, c’est tout ce qui permet à une équipe de comprendre, maintenir et faire évoluer son infrastructure sans dépendre d’une seule personne. Ce n’est pas une collection de fichiers qu’on remplit “quand on aura le temps”. C’est un outil de survie.

Ce que vous allez apprendre :

• Pourquoi la documentation est indispensable (même si “tout le monde sait”)
• Comment structurer en 5 familles distinctes
• La règle d’or : un document = une famille
• Comment mettre en place une documentation efficace (pas à pas)
• Comment organiser les responsabilités avec le modèle RACI

Pourquoi c’est indispensable

Connaissance tacite vs documentation

Il y a une différence fondamentale entre ce qui est documenté et ce qui est connu.

La connaissance tacite, c’est tout ce qui est dans la tête des experts de l’équipe. C’est Jean-Pierre qui sait que “le serveur de prod, faut le redémarrer dans cet ordre sinon ça plante”. C’est Marie qui connaît le mot de passe de l’ancien compte admin parce qu’elle l’a configuré il y a 3 ans.

Le problème ? Jean-Pierre part en vacances. Marie change d’entreprise. Et soudain, plus personne ne sait.

La documentation, c’est ce qui reste quand les experts ne sont pas là. C’est la différence entre une équipe résiliente et une équipe qui s’effondre au premier départ.

Règle d'or

Si une information est critique et qu’elle n’existe que dans la tête d’une seule personne, elle n’existe pas vraiment.

Les cinq bénéfices concrets

Vous pensez peut-être : “On est une petite équipe, on se parle tous les jours, pas besoin de tout écrire.” C’est une erreur classique.

Bénéfice	Sans documentation	Avec documentation
Temps de diagnostic	20 min à comprendre “c’est quoi ce serveur ?”	Ouvrir la page service, voir le diagramme, suivre le runbook
Intégration nouveaux	3 semaines à harceler les collègues	3 jours de lecture, puis questions ciblées
Astreinte	Appeler l’expert à 3h du matin	Suivre le runbook, résoudre 80% des incidents seul
Départ d’un expert	Panique, perte de savoir critique	Transition sereine, tout est documenté
Audit de sécurité	”Euh… je crois que c’est configuré comme ça…"	"Voici notre documentation des accès”

Ce qui se passe quand c’est mal structuré

Imaginez une bibliothèque où romans, manuels techniques, dictionnaires et bandes dessinées seraient mélangés sur les mêmes étagères. Trouver un livre serait un cauchemar.

C’est exactement ce qui se passe avec une doc mal structurée.

Problème	Conséquence
Tout mélangé dans un wiki	Impossible de trouver l’info en urgence
Runbook + architecture dans le même doc	Le lecteur se perd, skip des sections
Pas de structure définie	Chacun documente “à sa sauce”
Doublons partout	On ne sait plus quelle version est à jour

Les 5 familles de documentation

La solution : séparer la documentation en 5 familles, chacune avec un objectif clair, un format adapté, et un cycle de mise à jour approprié.

Vue d'ensemble

Famille	Question	Quand consulter	Format type
Cartographie	Qu’est-ce qui existe ?	Comprendre le paysage	Inventaires, listes
Architecture	Comment ça fonctionne ?	Diagnostic, onboarding	Diagrammes, schémas
Procédures	Comment agir ?	Incident, opération	Runbooks, checklists
Référentiel	Qui ? Quels accès ? Quelles règles ?	Organisation, droits	Annuaires, conventions
Historique	Pourquoi ce choix ?	Comprendre le passé	ADR, postmortems

Analogie bibliothèque

Famille	Équivalent bibliothèque	Ce qu’on y cherche
Cartographie	Catalogue, index	”Qu’avons-nous ?”
Architecture	Plans, cartes	”Comment c’est organisé ?”
Procédures	Manuels, guides pratiques	”Comment faire ?”
Référentiel	Annuaire, règlement	”Qui fait quoi ? Quelles règles ?”
Historique	Archives, journaux	”Pourquoi c’est comme ça ?”

Famille 1 : Cartographie

Question : Qu’est-ce qui existe ?

La cartographie recense tout ce qui compose votre système : serveurs, services, bases de données, API, connexions entre composants. C’est l’inventaire complet de votre infrastructure.

Ce qu’elle contient :

• Inventaire des serveurs (nom, rôle, IP, environnement)
• Liste des services (nom, fonction, owner, criticité)
• Registre des bases de données (type, version, connexions)
• Catalogue des API (endpoints, authentification)
• Matrice des dépendances (qui appelle qui)

Format recommandé : tableaux structurés

| Service | Owner | Criticité | Dépendances | SLA |
|---------|-------|-----------|-------------|-----|
| auth-api | @team-identity | Tier 1 | PostgreSQL, Redis | 99.9% |
| payment-service | @team-payment | Tier 1 | auth-api, Stripe | 99.95% |
| notification | @team-comm | Tier 2 | auth-api, SendGrid | 99% |

Cycle de mise à jour : à chaque changement (nouveau service, migration, décommissionnement).

Automatisation possible

La cartographie est le candidat idéal pour l’automatisation. Des outils comme une CMDB ou des scripts de découverte peuvent générer ces inventaires automatiquement.

Famille 2 : Architecture

Question : Comment ça fonctionne ?

L’architecture explique comment les composants interagissent, les flux de données, les protocoles utilisés. C’est la vision technique de votre système.

Ce qu’elle contient :

• Diagrammes de composants (boîtes et flèches montrant les services)
• Flux de données (utilisateur → API → DB)
• Diagrammes réseau (VLAN, firewalls, load balancers)
• Schémas de déploiement (Kubernetes, VMs, cloud)

Format recommandé : diagrammes simples + texte explicatif

Privilégiez les formats textuels (Mermaid, PlantUML) ou visuels maintenables :

Niveaux de détail (modèle C4) :

Niveau	Public	Détail
Contexte	Tous	Le système et ses interactions externes
Conteneurs	Développeurs	Services, bases, files d’attente
Composants	Équipe technique	Modules internes d’un service
Code	Contributeurs	Classes, fonctions (rarement documenté)

Cycle de mise à jour : lors de changements structurels. Revue annuelle minimum.

Le piège des diagrammes obsolètes

Un diagramme obsolète est pire qu’aucun diagramme : il induit en erreur. Préférez des diagrammes simples et maintenables à des chefs-d’œuvre qu’on n’ose plus toucher.

Famille 3 : Procédures

Question : Comment agir ?

Les procédures décrivent les actions à effectuer pour des opérations courantes ou des incidents. C’est ce qu’on consulte à 3h du matin.

Ce qu’elle contient :

Type	Usage	Exemple
Runbooks	Incidents, opérations techniques	Redémarrer le service auth
Checklists	Ne rien oublier	Checklist déploiement prod
Playbooks	Scénarios complexes multi-acteurs	Gestion incident majeur
Troubleshooting	Diagnostic pas à pas	”Erreur 500 sur /api/users”

Format recommandé : étapes numérotées avec validations

## Redémarrer le service auth

### Prérequis
- Accès SSH au serveur auth-prod-01
- Droits sudo

### Étapes

1. Vérifier l'état actuel
   ```bash
   systemctl status auth-service

Attendu : “active (running)” ou “failed”

2. Redémarrer le service

   sudo systemctl restart auth-service

3. Vérifier le redémarrage

   systemctl status auth-service

   Attendu : “active (running)” depuis < 1 minute

Si ça ne marche pas

• Logs : journalctl -u auth-service -n 100
• Escalade : @oncall-platform

**Cycle de mise à jour** : après chaque incident où la procédure a échoué ou
était incomplète.

### Famille 4 : Référentiel

**Question** : *Qui contacter ? Quels accès ? Quelles règles ?*

Le référentiel centralise les **informations organisationnelles** : contacts,
accès, conventions, politiques.

**Ce qu'elle contient :**

| Type | Contenu | Exemple |
|------|---------|---------|
| **Annuaire équipes** | Qui fait quoi, oncall, escalade | "L'équipe Platform gère Kubernetes" |
| **Matrice des accès** | Qui a accès à quoi | "Seuls les SRE ont accès prod" |
| **Conventions** | Standards de nommage, formats | "Les services : {domain}-{function}" |
| **Politiques** | Règles d'entreprise | "Tout changement prod nécessite une PR" |
| **Glossaire** | Définition des termes métier | "Un 'tenant' est un client B2B" |

**Format recommandé : tableaux et listes structurées**

```markdown
## Annuaire des équipes

| Équipe | Responsabilités | Contact Slack | Oncall |
|--------|-----------------|---------------|--------|
| Platform | Kubernetes, CI/CD, Observabilité | #team-platform | @oncall-platform |
| Identity | Auth, SSO, Permissions | #team-identity | @oncall-identity |
| Data | Bases de données, Analytics | #team-data | @oncall-data |

## Conventions de nommage

| Ressource | Format | Exemple |
|-----------|--------|---------|
| Serveur | {env}-{role}-{numero} | prod-web-01 |
| Service | {domaine}-{fonction} | payment-api |
| Base de données | {service}-{type}-{env} | auth-postgres-prod |

Cycle de mise à jour :

• Annuaire : à chaque arrivée/départ
• Accès : revue trimestrielle (audit sécurité)
• Conventions : rarement (décision collective)

Famille 5 : Historique

Question : Pourquoi ce choix ? Que s’est-il passé ?

L’historique conserve la mémoire des décisions et des événements pour éviter de répéter les erreurs et comprendre le contexte.

Ce qu’elle contient :

Type	Usage	Exemple
ADR	Documenter une décision technique	”Pourquoi PostgreSQL plutôt que MySQL”
Postmortems	Analyser un incident	”Panne du 15 mars 2024”
Changelog	Historique des changements	”v2.3.0 : ajout cache Redis”
Journal migrations	Suivi des migrations	”Migration Oracle → PostgreSQL”

Format recommandé : template ADR

# ADR-003 : Adoption de PostgreSQL pour les sessions

**Date** : 2024-01-15
**Statut** : Accepté
**Décideurs** : @alice, @bob, @charlie

## Contexte
Nous devons stocker les sessions utilisateurs avec haute disponibilité
et transactions ACID.

## Options considérées

| Option | Avantages | Inconvénients |
|--------|-----------|---------------|
| Redis | Rapide, simple | Pas ACID |
| PostgreSQL | ACID, SQL, réplication native | Plus lent |
| DynamoDB | Serverless, scalable | Vendor lock-in |

## Décision
PostgreSQL — ACID obligatoire, équipe familière.

## Conséquences
- [+] Cohérence des données garantie
- [-] Latence légèrement supérieure
- [Action] Mettre en place PgBouncer

Cycle de mise à jour :

• ADR : immuables (nouvelle décision = nouvel ADR)
• Postmortems : dans les 5 jours suivant l’incident
• Changelog : à chaque release

Règle d’or : un document = une famille

Le piège le plus courant est de mélanger les familles dans un même document.

❌ Anti-pattern	✅ Bonne pratique
Service Overview avec runbooks intégrés	Service Overview + liens vers runbooks séparés
ADR avec procédure de migration	ADR (décision) + Runbook (procédure)
Annuaire avec architecture réseau	Page Équipes + Page Architecture réseau
Postmortem avec checklist intégrée	Postmortem + action item “créer checklist”

Pourquoi cette séparation ?

• Cycle de mise à jour différent : un annuaire change souvent, une architecture rarement
• Public différent : l’oncall veut la procédure, pas l’historique des décisions
• Recherche facilitée : on sait où chercher selon le besoin

Mettre en place sa documentation (pas à pas)

1. Faire l’inventaire de l’existant

   Où se trouve la documentation actuelle ? Wiki ? Notion ? README ? Post-its ? Qu’est-ce qui est à jour ? Qu’est-ce qui manque cruellement ?

   Exercice : listez toutes les fois où vous avez dû “demander à quelqu’un” ces dernières semaines. Chaque question récurrente → candidat à documenter.

2. Choisir un outil central

   Critère	Pourquoi c’est important
   Recherche efficace	Si on ne trouve pas, ça n’existe pas
   Versioning	Savoir ce qui a changé et quand
   Collaboration	Plusieurs contributeurs
   Accessibilité	Disponible même en cas d’incident

   Options : Wiki (Confluence, Notion), Docs-as-code (MkDocs, Docusaurus), README Git.

3. Définir une structure claire

   • RépertoireServices/

     • Répertoireservice-paiement/

       • overview.md
       • architecture.md
       • Répertoirerunbooks/

         • …
   • RépertoireInfrastructure/

     • reseau.md
     • serveurs.md
   • RépertoireProcedures-transverses/

     • gestion-incidents.md
     • deploiement.md
   • RépertoireDecisions-ADR/

     • 001-choix-postgresql.md
   • RépertoireContacts-et-acces/

     • equipe.md
     • acces.md

4. Créer les pages essentielles

   Pour chaque service critique :

   Page	Pourquoi c’est prioritaire
   Vue d’ensemble	Point d’entrée, criticité
   Architecture	Comprendre comment ça marche
   Dépendances	Évaluer l’impact d’une panne
   Runbooks	Ce qu’on consulte à 3h du matin
   Contacts	Qui appeler en cas d’urgence

   Commencez par les services les plus critiques.

5. Maintenir à jour

   Règle 1 : à chaque changement, mettre à jour la doc (pas “plus tard”).

   Règle 2 : revue trimestrielle des pages clés.

   Règle 3 : chaque page a un propriétaire (owner).

Docs-as-code

Si votre équipe utilise déjà Git, le docs-as-code est souvent le meilleur choix. La documentation suit les mêmes workflows que le code : branches, pull requests, reviews. Pas de merge sans doc à jour.

Gouvernance multi-équipe : le modèle RACI

Dans une organisation avec plusieurs équipes, la documentation devient un terrain vague si personne n’est clairement responsable.

Définir les rôles avec RACI

Lettre	Rôle	Ce que ça veut dire
R	Responsible	Fait le travail (rédige, met à jour)
A	Accountable	Valide et est responsable du résultat final
C	Consulted	Consulté avant de finaliser (expert, relecteur)
I	Informed	Informé après (ne participe pas, doit savoir)

Règle d'or du RACI

Il ne peut y avoir qu’un seul Accountable par document. “Tout le monde est responsable” = personne ne l’est.

Exemple de matrice RACI

                          │ Owner     │ Dev       │ Archi     │ Équipe
                          │ (Tech Lead│ (service) │           │
──────────────────────────┼───────────┼───────────┼───────────┼─────────
Créer la page service     │     A     │     R     │     C     │    I
Mettre à jour après       │     A     │     R     │     C     │    I
changement                │           │           │           │
Valider publication       │     A     │     -     │     C     │    -
Revue trimestrielle       │     A     │     R     │     C     │    -
Signaler une erreur       │     I     │     R     │     -     │    R

Automatiser avec CODEOWNERS

Si vous utilisez GitHub/GitLab avec docs-as-code, le fichier CODEOWNERS assigne automatiquement les reviewers :

# Documentation infrastructure : l'équipe ops doit valider
/docs/infrastructure/       @ops-team

# Documentation API : l'équipe backend doit valider
/docs/api/                  @backend-team

# Documentation sécurité : l'équipe sécu doit valider
/docs/security/             @security-team

La PR ne peut pas être mergée tant que le reviewer n’a pas approuvé. C’est du RACI automatisé.

Gérer les conflits entre équipes

Situation	Solution
Deux équipes veulent modifier le même doc	L’Owner tranche
Désaccord sur le contenu technique	Escalade architecte, décision documentée (ADR)
Documentation en doublon	Fusionner, désigner un seul owner, supprimer le doublon
Personne ne veut maintenir un doc	Assigner un owner explicitement, ou archiver

Les erreurs classiques à éviter

Anti-pattern	Ce qui se passe	Comment l’éviter
Documentation fantôme	Existe mais personne ne sait où	Un seul outil, structure claire
Documentation obsolète	Schéma de 2019, infra changée 3 fois	Mise à jour intégrée au workflow
Trop de détails	50 pages que personne ne lit	Aller à l’essentiel
Pas assez de détails	”Voir avec Jean-Pierre”	Si c’est critique, c’est documenté
Silos documentaires	Chaque équipe son wiki	Un outil commun ou liens croisés
Pas de recherche	Impossible de trouver	Recherche full-text, bons titres
Pas de propriétaire	”Doc de personne = doc de tout le monde”	Un owner explicite par section
Ownership flou	”Équipes X et Y responsables”	Un seul Accountable
Validation sans fin	5 approbateurs, 3 semaines pour une typo	Simplifier le workflow

Checklists récapitulatives

Checklist “Minimum viable”

Si vous partez de zéro, commencez par ces éléments :

• Outil de documentation choisi et accessible à tous
• Cartographie des services (liste avec criticité)
• Schéma réseau (comment les machines sont connectées)
• Runbooks pour les incidents les plus courants
• Annuaire (qui appeler en cas de problème)
• Recherche fonctionnelle
• Chaque service critique a au moins une page
• Owners identifiés pour chaque section

Checklist “Maturité”

Une fois les bases en place :

• ADR pour les décisions techniques importantes
• Versioning (git ou historique wiki)
• Revues trimestrielles planifiées
• Templates pour créer de nouvelles pages
• Feedback loop (signaler une doc obsolète)
• Accès en incident (doc accessible si infra en panne)
• CI/CD docs (build et déploiement automatiques)
• Matrice RACI documentée
• CODEOWNERS configuré (si docs-as-code)
• Onboarding contributeurs documenté

Checklist avant création d’un document

• Quelle famille ? (Cartographie / Architecture / Procédures / Référentiel / Historique)
• Où le ranger ? (Dossier correspondant)
• Existe-t-il déjà ? (Éviter les doublons)
• Qui va le maintenir ? (Owner défini)
• Quel cycle de mise à jour ?

À retenir

1. Une info non documentée n’existe pas — si elle n’est que dans la tête de Jean-Pierre, elle disparaît avec lui.

2. 5 familles distinctes — Cartographie, Architecture, Procédures, Référentiel, Historique. Ne les mélangez pas.

3. Un document = une famille — cycles de mise à jour et publics différents.

4. Un seul Accountable par document — “tout le monde responsable” = personne.

5. Mise à jour intégrée au workflow — pas de merge sans doc à jour.

6. Commencez petit — services critiques + runbooks incidents courants + annuaire. Le reste viendra.

Ressources complémentaires

Runbooks Comment écrire des procédures d'intervention efficaces

Checklists La méthode Atul Gawande pour ne rien oublier

Service Overview Créer la carte d'identité d'un service

Sources

• Write the Docs - Documentation Guide ↗ — La référence communautaire
• Divio Documentation System ↗ — Framework de structuration
• Architecture Decision Records ↗ — Documenter les décisions techniques
• Google SRE Book - Documentation ↗ — La vision Google
• Asana RACI Guide ↗ — Le modèle RACI
• GitHub CODEOWNERS ↗ — Automatiser les validations