Reviews et fraîcheur : garder la documentation à jour

Imaginez la scène. 3h du matin, une alerte critique. L’ingénieur d’astreinte ouvre le runbook « Redémarrage API principale ». Il suit les étapes… et rien ne fonctionne. Le service a été migré il y a 6 mois, les commandes pointent vers des serveurs qui n’existent plus. Résultat : 2 heures de galère au lieu de 15 minutes.

Ce scénario arrive tous les jours dans des équipes qui n’ont pas de processus de review documentaire. Ce guide vous apprend à l’éviter.

Pourquoi la documentation vieillit mal

Une documentation obsolète est pire qu’une absence de documentation. Pourquoi ? Parce qu’elle donne une fausse confiance. L’opérateur suit une procédure qui ne fonctionne plus, perd du temps, aggrave parfois la situation.

Sans processus de maintenance actif, voici ce qui se passe :

La ligne du haut montre la dégradation naturelle :

1. Mois 1 : Documentation créée, testée, parfaite ✓
2. Mois 3-6 : Petits changements de configuration (non documentés)
3. Mois 9-12 : Migration majeure, document complètement obsolète ✗

La ligne du bas montre le cycle avec reviews régulières :

1. Mois 1 : Documentation créée ✓
2. Mois 3 : Review planifiée → corrections mineures 🔍
3. Mois 6 : Document toujours fiable ✓

Loi de l'entropie documentaire

Toute documentation livrée à elle-même tend vers l’obsolescence. C’est inévitable. Seul un processus actif de maintenance peut inverser cette tendance.

L’analogie du frigo

Imaginez votre réfrigérateur à la maison :

Situation	Sans vérification	Avec vérification hebdo
Yaourt périmé	Découvert après 3 mois, moisi	Consommé ou jeté à temps
Reste oublié	Développe des formes de vie inconnues	Identifié et traité rapidement
Organisation	Chaos, impossible de trouver quoi que ce soit	Rangé, accessible

La documentation, c’est pareil. Vous devez ouvrir le frigo régulièrement pour vérifier ce qui est encore bon et ce qui doit partir.

Les cinq qualités d’une documentation fraîche

Pour qu’une documentation soit vraiment utile, elle doit répondre à cinq critères. Utilisez cette grille lors de vos reviews :

Qualité	Question à poser	Conséquence si « non »
Exacte	Les informations sont-elles correctes ?	Erreurs, incidents aggravés
Complète	Manque-t-il des étapes ?	Procédure impossible à terminer
Actuelle	Reflète-t-elle l’état actuel du système ?	Confusion, perte de temps
Accessible	Peut-on la trouver facilement ?	Documentation inutilisée
Testée	Quelqu’un l’a-t-il suivie récemment ?	Bugs cachés, étapes manquantes

Le test ultime

Demandez à quelqu’un qui ne connaît pas le sujet de suivre la procédure pas à pas. S’il bloque ou fait des erreurs, votre documentation n’est pas assez bonne, même si elle vous semble claire.

Définir une cadence de review

Tous les documents n’ont pas besoin de la même fréquence de vérification. Un runbook utilisé en situation d’urgence mérite plus d’attention qu’un document historique.

Fréquences recommandées par type

Haute fréquence

Documents critiques — review mensuelle

Type	Pourquoi cette fréquence
Runbook incident critique	Utilisé en urgence, doit être parfait
Procédure de sécurité	Contexte de menace évolue vite
Checklist déploiement	Pipeline change régulièrement

Ces documents peuvent faire la différence entre un incident résolu en 15 minutes et une crise de plusieurs heures.

Fréquence moyenne

Documents opérationnels — review trimestrielle

Type	Pourquoi cette fréquence
Runbook opération courante	Changements moins fréquents
Service Overview	Architecture évolue régulièrement
Guide onboarding	À tester avec chaque nouveau

Ces documents évoluent avec l’infrastructure, mais pas quotidiennement.

Basse fréquence

Documents de référence — review annuelle ou jamais

Type	Pourquoi cette fréquence
ADR (Architecture Decision Record)	Vérifier si décision toujours valide
Postmortem	Document historique figé (jamais de review)
Documentation légale/conformité	Seulement si réglementation change

Les postmortems ne doivent jamais être modifiés après publication (ils documentent ce qui s’est passé à un instant T).

Exemple de calendrier annuel

Voici un calendrier type pour une équipe moyenne :

JANVIER   : Review runbooks critiques (semaine 2)
FÉVRIER   : —
MARS      : Review Service Overviews (semaine 1)
AVRIL     : Review runbooks critiques (semaine 2)
MAI       : —
JUIN      : Review complète : runbooks ops + Service Overviews (semaine 1)
JUILLET   : Review runbooks critiques (semaine 2)
AOÛT      : —
SEPTEMBRE : Review Service Overviews (semaine 1)
OCTOBRE   : Review runbooks critiques + ADRs annuels (semaine 2)
NOVEMBRE  : —
DÉCEMBRE  : Review annuelle complète - tout le corpus (semaine 1)

Astuce pratique

Bloquez ces créneaux dans le calendrier d’équipe à l’avance. Si ce n’est pas planifié, ça n’arrivera pas. Traitez les reviews de documentation comme des réunions obligatoires.

Comment faire une review efficace

Une review ne consiste pas à survoler le document en 30 secondes. C’est un processus structuré en plusieurs étapes.

1. Identifier les documents à reviewer

   Commencez par établir la liste des documents concernés :

   • Filtrez par date de dernière review
   • Priorisez les documents critiques
   • Vérifiez les signalements utilisateurs (« Ce doc m’a posé problème »)

   # Exemple : trouver les docs non reviewées depuis 90 jours
   find docs/ -name "*.md" -exec grep -l "last_reviewed:" {} \; | while read f; do
     last=$(grep "last_reviewed:" "$f" | cut -d' ' -f2)
     days=$(( ($(date +%s) - $(date -d "$last" +%s)) / 86400 ))
     [ $days -gt 90 ] && echo "⚠️ $f : $days jours"
   done

2. Vérifier les métadonnées

   Avant de plonger dans le contenu, validez les informations de base :

   Élément	Question	Action si problème
   Date de mise à jour	Réaliste ?	Investiguer l’historique git
   Owner	Toujours dans l’équipe ?	Réassigner
   Liens internes	Fonctionnent-ils tous ?	Corriger ou supprimer
   Tags/catégories	Toujours pertinents ?	Mettre à jour

3. Valider le contenu technique

   C’est l’étape la plus importante. Vérifiez :

   • Commandes : fonctionnent-elles toujours ?
   • Chemins : les fichiers/dossiers existent-ils ?
   • Captures d’écran : reflètent-elles l’interface actuelle ?
   • Versions : les numéros de version sont-ils à jour ?

   Ne pas faire semblant

   Si vous ne pouvez pas tester réellement une procédure (environnement de test non disponible), notez-le clairement. Une review « visuelle » vaut mieux que rien, mais ne garantit pas le fonctionnement.

4. Décider et documenter

   À l’issue de la review, trois options :

   Décision	Quand	Action
   OK	Document correct	Mettre à jour last_reviewed
   À mettre à jour	Corrections nécessaires	Créer ticket, deadline 48h
   À archiver	Document obsolète	Déplacer vers /archives/

   Documentez systématiquement la review :

   <!-- Review: 2025-01-15 par @alice - OK, liens vérifiés, commandes testées -->

Automatiser la détection d’obsolescence

Les reviews manuelles sont indispensables, mais l’automatisation peut vous aider à identifier les documents qui nécessitent une attention particulière.

Métadonnées dans le frontmatter

Standardisez vos frontmatters pour faciliter l’automatisation :

---
title: "Runbook : Redémarrage API principale"
last_updated: 2025-01-15
last_reviewed: 2025-01-15
review_frequency: monthly   # monthly | quarterly | yearly | never
owner: "@alice"
criticality: high          # high | medium | low
---

Script de vérification CI

Intégrez la vérification dans votre pipeline CI/CD :

Script Bash

check-doc-freshness.sh

#!/bin/bash
EXIT_CODE=0

find docs/ -name "*.md" | while read -r file; do
  # Extraire les métadonnées
  last_review=$(grep "last_reviewed:" "$file" | cut -d' ' -f2)
  frequency=$(grep "review_frequency:" "$file" | cut -d' ' -f2)

  # Calculer les jours depuis dernière review
  if [ -n "$last_review" ]; then
    days=$(( ($(date +%s) - $(date -d "$last_review" +%s)) / 86400 ))

    # Seuils selon fréquence
    case "$frequency" in
      monthly)   threshold=45 ;;
      quarterly) threshold=120 ;;
      yearly)    threshold=400 ;;
      *)         threshold=90 ;;
    esac

    if [ "$days" -gt "$threshold" ]; then
      echo "::warning file=$file::Review en retard ($days jours)"
      EXIT_CODE=1
    fi
  else
    echo "::warning file=$file::Pas de date de review"
  fi
done

exit $EXIT_CODE

GitHub Action

.github/workflows/doc-freshness.yml

name: Documentation Freshness Check

on:
  schedule:
    - cron: '0 9 * * 1'  # Chaque lundi à 9h
  workflow_dispatch:

jobs:
  check-freshness:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check document freshness
        run: ./scripts/check-doc-freshness.sh

      - name: Create issue if problems
        if: failure()
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: '📚 Documentation à reviewer',
              body: 'Des documents nécessitent une review. Voir le workflow.',
              labels: ['documentation', 'maintenance']
            })

Alertes automatiques

Configurez des notifications quand :

Événement	Canal recommandé	Destinataire
Doc non reviewée depuis > seuil	Slack / Email	Owner du document
Owner a quitté l’équipe	Ticket JIRA	Manager / Tech Lead
Lien cassé détecté	Slack	Équipe documentation
Aucun owner défini	Ticket	Product Owner

La review post-incident : un réflexe obligatoire

Après chaque incident, la documentation doit être revue systématiquement. C’est le moment idéal pour détecter les écarts entre la théorie (la doc) et la pratique (ce qui a vraiment fonctionné).

Questions à poser

Lors du débrief post-incident, posez ces questions :

• Le runbook utilisé était-il à jour ?
• Manquait-il des étapes cruciales ?
• Y avait-il des erreurs dans les commandes ?
• A-t-on découvert une nouvelle procédure à documenter ?
• Le Service Overview reflète-t-il la réalité ?
• L’ordre des étapes était-il optimal ?

Actions à prendre

Si un problème de documentation est identifié :

1. Créer un ticket immédiatement (pas « on verra plus tard »)
2. Assigner à l’owner du document concerné
3. Deadline : 48h après l’incident
4. Review croisée avant merge (pas l’auteur seul)

Dans le postmortem, ajoutez systématiquement une section documentation :

## Actions documentation

| Action | Owner | Deadline | Statut |
|--------|-------|----------|--------|
| Mettre à jour runbook restart-api | @alice | J+2 | 🟡 En cours |
| Ajouter étape vérification logs | @bob | J+2 | ⬜ À faire |
| Créer runbook pour nouveau cas | @charlie | J+5 | ⬜ À faire |

Ne pas modifier les postmortems

Les postmortems sont des documents historiques. Ils décrivent ce qui s’est passé à un instant T. Ne les modifiez jamais, même si les informations deviennent obsolètes. Leur valeur est précisément d’être un instantané fidèle.

Archiver plutôt que supprimer

Quand une documentation devient obsolète (service décommissionné, procédure abandonnée), ne la supprimez pas. Archivez-la.

Pourquoi archiver ?

Raison	Explication
Historique préservé	Comprendre pourquoi certaines décisions ont été prises
Référence future	Le sujet peut revenir (migration inverse, audit)
Audit trail	Prouver que la procédure existait à une date donnée
Formation	Montrer l’évolution des pratiques aux nouveaux

Structure d’archivage recommandée

docs/
├── actifs/               ← Documentation vivante
│   ├── services/
│   ├── runbooks/
│   └── onboarding/
└── archives/             ← Documentation figée
    ├── 2023/
    │   └── api-v1-runbook.md
    ├── 2024/
    │   └── ancien-monitoring.md
    └── 2025/

Marquer clairement les archives

Ajoutez un bandeau visible en haut de chaque document archivé :

:::caution[Document archivé]
Ce document n'est plus maintenu.
**Raison** : Service décommissionné le 2025-01-15.
**Pour référence historique uniquement.**
:::

Mesurer la fraîcheur documentaire

Ce qui se mesure s’améliore. Voici les métriques clés à suivre :

Métrique	Cible	Seuil d’alerte	Comment mesurer
% docs reviewées dans les temps	> 90%	< 80%	Script CI hebdomadaire
Âge moyen depuis dernière review	< 90 jours	> 180 jours	Dashboard automatisé
Docs modifiées après incident	100% des cas	< 80%	Checklist postmortem
Liens cassés	0	> 0	Linter automatique
Docs sans date de review	0	> 5%	Script CI
Docs sans owner	0	> 0	Rapport mensuel

Tableau de bord suggéré

┌─────────────────────────────────────────────────────────────┐
│ 📊 SANTÉ DOCUMENTAIRE - Janvier 2025                        │
├─────────────────────────────────────────────────────────────┤
│ Documents à jour      : ████████████████████░░ 85%  ⚠️      │
│ Reviews ce mois       : 12 / 15 planifiées                  │
│ Âge moyen             : 67 jours  ✓                         │
│ Liens cassés          : 3  ⚠️ (voir ticket #1234)           │
│ Docs sans owner       : 1  ⚠️ (runbook-legacy)              │
└─────────────────────────────────────────────────────────────┘

Anti-patterns à éviter

Anti-pattern	Problème	Solution
« On reviewera quand on aura le temps »	Le temps n’arrive jamais	Bloquer des créneaux fixes au calendrier
Review = « ça a l’air bon »	Aucune vraie vérification	Checklist obligatoire + test réel
Supprimer les vieilles docs	Perte d’historique	Archiver avec bandeau explicatif
Pas de date de review	Impossible de savoir l’état	Frontmatter obligatoire en CI
Review par l’auteur seul	Biais de confirmation	Toujours une review croisée
Ignorer les retours utilisateurs	Problèmes récurrents	Canal de feedback + suivi

À retenir

La dégradation est naturelle

Sans maintenance active, toute documentation devient obsolète. Ce n’est pas un échec, c’est une loi de la nature.

Planifiez les reviews

Ce qui n’est pas au calendrier n’arrive pas. Bloquez du temps dédié.

Automatisez la détection

Scripts CI, alertes Slack, dashboards : laissez les machines vous alerter des problèmes.

Archivez, ne supprimez pas

L’historique a de la valeur. Déplacez plutôt que détruire.

Ressources complémentaires

Ownership et Definition of Done Qui maintient quoi et quand un document est-il terminé ?

Anti-patterns documentation Les erreurs classiques à éviter absolument

Google SRE Workbook Chapitre sur l'amélioration continue des services

Continuous Documentation (TheNewStack) Intégrer la documentation dans votre CI/CD