Documenter : créer une documentation qui survit

Résoudre ce cauchemar récurrent

Imaginez : il est 2h du matin. Votre téléphone sonne. Alerte critique sur le service de paiement. Vous vous connectez, le cœur battant. Et là, la question fatidique : “Comment on redémarre ce truc, déjà ?”

Vous cherchez dans le wiki. Rien. Vous fouillez Slack. Des bribes d’info datant de 2022. Vous appelez Jean-Pierre, le seul qui sait. Il ne répond pas — il est en vacances.

Ce cauchemar a un nom : l’absence de documentation.

Ce n’est pas un problème de paresse. C’est un problème systémique. Les équipes qui documentent mal ne sont pas incompétentes — elles n’ont simplement pas la bonne méthode.

Objectif de ce parcours

À la fin de ce parcours, vous saurez :

1. Comprendre pourquoi la documentation est un outil de survie, pas une corvée
2. Structurer votre documentation en 5 familles distinctes
3. Créer les documents essentiels : Service Overviews, runbooks, postmortems
4. Gouverner : définir qui maintient quoi, et à quelle fréquence
5. Choisir les bons outils et évaluer votre maturité

Ce parcours est progressif. Chaque étape s’appuie sur la précédente.

À qui s’adresse ce parcours ?

Vous êtes au bon endroit si vous êtes :

• SRE ou ops gérant des systèmes en production
• Tech Lead voulant structurer la documentation de l’équipe
• Développeur fatigué de chercher l’info pendant les incidents
• Manager souhaitant réduire le “bus factor” de l’équipe

Prérequis :

• Avoir un système en production (même petit)
• Connaître les bases de Git (commits, branches)
• Être prêt à investir du temps maintenant pour en gagner plus tard

Votre parcours d’apprentissage

Ce parcours suit une progression logique en 5 étapes :

Durée totale estimée : environ 3 heures de lecture active.

---

Étape 1 — Pourquoi documenter (et ce que ça change)

Avant de définir une organisation, comprenons pourquoi la documentation est un investissement, pas une perte de temps.

L’analogie de l’assurance incendie

Personne n’aime payer une assurance incendie. C’est de l’argent “perdu” tant que tout va bien. Mais le jour où le feu se déclare, vous êtes content de l’avoir.

La documentation, c’est pareil.

Situation	Sans documentation	Avec documentation
Incident à 3h du matin	”J’appelle Jean-Pierre"	"Je suis le runbook”
Nouveau dans l’équipe	3 semaines pour être autonome	3 jours + questions ciblées
Départ d’un expert	Panique, perte de savoir	Transition sereine
Audit de sécurité	”Euh… je crois que…"	"Voici notre documentation”

Le “bus factor” : votre indicateur de risque

Le bus factor mesure combien de personnes peuvent disparaître avant que l’équipe soit bloquée.

• Bus factor = 1 → une seule personne détient l’information = risque maximal
• Bus factor = 3+ → l’information est partagée = équipe résiliente

Règle d'or

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

Test rapide : pour chaque service critique, demandez-vous :

• Qui sait le redémarrer ? (1 personne = danger)
• Qui connaît l’architecture ? (1 personne = danger)
• Qui peut déployer en production ? (1 personne = danger)

---

Étape 2 — Gouverner : qui maintient quoi

Une documentation sans gouvernance meurt en 6 mois. Avant même de créer vos premiers documents, définissez qui sera responsable de quoi.

Ownership : chaque doc a un responsable

Rôle	Responsabilité
Owner	Maintient le document à jour
Contributeurs	Proposent des modifications
Reviewers	Valident les changements

Règle pratique

Si personne n’est responsable, personne ne maintient. Assignez un owner à chaque document critique.

Definition of Done : intégrer la doc

Une fonctionnalité n’est pas terminée tant que la documentation n’est pas mise à jour.

Checklist PR :

• Tests passent
• Code review approuvée
• Documentation mise à jour
• CHANGELOG complété

Cycles de review

Type	Fréquence	Déclencheur
Runbooks critiques	Trimestrielle	+ après chaque utilisation
Service Overviews	Semestrielle	+ lors de changement majeur
ADR	Jamais	Immuables (nouvelle décision = nouvelle ADR)
Postmortems	Jamais	Archive historique

Ownership et Definition of Done RACI, intégration dans les PRs, transfert de responsabilité.

Reviews et fraîcheur Cycles de review, automatisation, post-incident.

Anti-patterns à éviter Les 10 erreurs classiques et comment les corriger.

---

Étape 3 — Structurer en 5 familles

Une documentation efficace n’est pas un wiki fourre-tout. Elle est structurée en familles, chacune répondant à un besoin différent.

Famille	Question	Exemple	Mise à jour
Cartographie	Qu’est-ce qui existe ?	Inventaire serveurs, services	À chaque changement
Architecture	Comment ça fonctionne ?	Diagrammes, flux de données	Lors de refonte
Procédures	Comment agir ?	Runbooks, checklists	Après chaque incident
Référentiel	Qui contacter ?	Annuaire, conventions	Arrivées/départs
Historique	Pourquoi ce choix ?	ADR, postmortems	Immuable

Ne pas tout mélanger

Un document = une famille. Si votre doc mélange procédure et architecture, le lecteur se perd et ne trouve pas ce qu’il cherche en urgence.

Structure de dossiers recommandée

documentation/
├── services/                    # Cartographie + Architecture par service
│   ├── auth-api/
│   │   ├── overview.md         # Carte d'identité du service
│   │   ├── architecture.md     # Diagrammes
│   │   └── runbooks/           # Procédures spécifiques
│   └── payment-service/
│
├── procedures/                  # Procédures transverses
│   ├── deploiement.md
│   └── gestion-incidents.md
│
├── referentiel/                 # Référentiel
│   ├── equipes.md
│   └── conventions.md
│
└── decisions/                   # Historique
    ├── adr/
    └── postmortems/

Concevoir et Structurer sa Documentation Opérationnelle Les 5 familles en détail, formats recommandés, cycles de mise à jour.

---

Étape 4 — Créer les documents essentiels

Maintenant que vous avez la gouvernance et la structure, passons à la création. Voici les 4 types de documents que toute équipe devrait avoir.

3.1 Service Overview — la carte d’identité

Chaque service critique doit avoir sa “carte d’identité” : ce qu’il fait, qui le maintient, comment il fonctionne.

Contenu minimum :

• Nom, owner, criticité, SLA
• Ce que fait le service (2-3 phrases)
• Architecture simplifiée
• Dépendances critiques
• Contacts et escalade

Guide : Service Overview Comment créer la carte d'identité d'un service en 8 étapes.

3.2 Runbooks — les procédures d’urgence

Un runbook est une recette de cuisine pour résoudre un problème spécifique. Étapes numérotées, commandes exactes, validations.

Caractéristiques :

• 1 runbook = 1 problème précis
• Étapes numérotées avec commandes
• Validation après chaque étape
• Section “Si ça ne marche pas”

Guide : Runbooks Créer des procédures d'urgence efficaces — l'analogie de la recette de cuisine.

3.3 Postmortems — apprendre des incidents

Un postmortem documente ce qui s’est passé, pourquoi, et comment éviter que ça se reproduise. Sans chercher de coupable.

Structure :

• Timeline factuelle
• Impact (durée, utilisateurs affectés)
• Causes racines (5 Whys)
• Actions correctives avec owners

Guide : Postmortems blameless Apprendre des incidents sans chercher de coupable.

3.4 Checklists — ne rien oublier

Une checklist n’est pas un runbook. C’est une liste de points à vérifier pour ne rien oublier lors d’une opération.

Usages :

• Pré-déploiement (10-15 points)
• Post-incident (validation complète)
• Onboarding (accès, outils, docs)

Guide : Checklists Ne plus rien oublier en exploitation — méthode Atul Gawande.

---

Étape 5 — Choisir les outils et évaluer sa maturité

Dernière étape : choisir où stocker votre documentation et mesurer votre progression.

Docs-as-Code vs Wiki

Approche	Avantages	Inconvénients
Docs-as-Code (Git + Markdown)	Versionné, reviewable, proche du code	Courbe d’apprentissage
Wiki (Confluence, Notion)	Accessible à tous, WYSIWYG	Pas de review, dérive facile

Recommandation : Docs-as-Code pour la doc technique, Wiki pour la doc organisationnelle.

Outils recommandés

Outil	Type	Meilleur pour
MkDocs	Docs-as-Code	Documentation technique simple
Starlight	Docs-as-Code	Sites de documentation complets
Docusaurus	Docs-as-Code	Documentation produit
Antora	Docs-as-Code	Documentation multi-projets
Notion	Wiki	Documentation légère, partagée
Confluence	Wiki	Documentation d’entreprise

Docs-as-Code et outils Comparatif MkDocs, Docusaurus, Starlight, GitBook, Confluence.

Auto-évaluation maturité Questionnaire en 15 questions pour mesurer votre niveau.

---

Maintenant : passer à la pratique

Vous avez les bases et vous avez choisi votre outil. Voici comment démarrer selon votre situation :

Urgence (1 jour)

Minimum vital pour survivre :

1. Lister vos 3 services les plus critiques
2. Pour chacun, créer un Service Overview minimal
3. Documenter 1 runbook pour l’incident le plus fréquent

→ Résultat : vous pouvez gérer les incidents courants

Fondations (1 semaine)

Base solide :

1. Compléter les Service Overviews des services critiques
2. Créer 3-5 runbooks (incidents fréquents)
3. Définir l’ownership (qui maintient quoi)
4. Choisir 1 outil centralisé

→ Résultat : onboarding possible, incidents gérables

Maturité (1 mois)

Organisation pérenne :

1. Couvrir tous les services avec overviews complets
2. Runbooks pour tous les scénarios d’incident
3. Process de review trimestriel
4. Templates standardisés pour chaque type
5. Métriques d’usage

→ Résultat : équipe autonome, transferts fluides

Auto-évaluation

Avant de passer aux guides détaillés, vérifiez votre compréhension :

• Je sais expliquer pourquoi la documentation est un investissement
• Je connais les 5 familles de documentation
• Je peux distinguer runbook, checklist et playbook
• Je comprends le concept d’ownership
• Je sais quand faire une review de documentation
• Je connais la différence entre Docs-as-Code et Wiki

Toutes les cases cochées ? Commencez par créer votre premier Service Overview ou faites l’auto-évaluation maturité pour identifier vos priorités.

---

Guides par outil

Une fois les fondamentaux maîtrisés, choisissez votre outil :

Astro Starlight Le framework utilisé pour ce site — moderne et performant.

MkDocs Simple, en Python, idéal pour débuter avec Docs-as-Code.

Docusaurus Par Meta, pour la documentation produit.

Modèle C4 Structurer vos diagrammes d'architecture.