Ownership : qui maintient la documentation ?

Vous avez créé une belle documentation. Tout le monde l'a félicitée. Six mois plus tard, elle est obsolète. Personne ne l'a mise à jour parce que... personne ne savait que c'était son travail.

Ce scénario se répète dans la majorité des équipes techniques. Non pas par paresse, mais par absence de clarté sur les responsabilités.

Ce guide vous apprend à définir précisément qui est responsable de quoi, pour que votre documentation reste vivante, utile et digne de confiance.

Le problème : "C'est à qui de mettre à jour ?"

Un incident révélateur

Imaginez cette situation, vécue par une équipe e-commerce :

L'équipe Plateforme crée un runbook pour le service de paiement
Trois mois plus tard, l'équipe Checkout modifie la configuration du service
L'équipe Plateforme n'est pas informée, le runbook reste inchangé
Un incident survient à 3h du matin. L'astreinte suit le runbook obsolète
La procédure échoue. L'incident dure 2h au lieu des 15 minutes prévues

Qui est fautif ? La réponse instinctive pointe vers l'équipe Checkout qui n'a pas mis à jour la doc. Mais la vraie question est : savaient-ils qu'ils devaient le faire ?

Le problème n'est pas la négligence. C'est l'absence de règles claires sur l'ownership. Je sais de quoi je parle : j'ai vu ce scénario se répéter plusieurs fois dans différentes structures.

Ce que coûte l'absence d'ownership

Le flou sur les responsabilités ne reste jamais un problème abstrait, il se paie en incidents concrets. Le tableau relie chaque conséquence organisationnelle à son impact visible sur le terrain. Lisez-le comme une chaîne : une documentation obsolète prolonge un incident, un « ce n'est pas mon job » nourrit la perte de confiance, et l'ensemble finit en dette technique invisible jusqu'à la prochaine astreinte.

Conséquence	Impact concret
Documentation obsolète	Procédures qui échouent, incidents prolongés
Duplication d'efforts	Plusieurs personnes rédigent la même chose
Conflits d'équipe	"Ce n'est pas mon job de maintenir ça"
Perte de confiance	L'équipe cesse de consulter la doc
Dette technique cachée	Accumulation de docs orphelines

Le modèle RACI appliqué à la documentation

Le modèle RACI est un framework de clarification des responsabilités utilisé en gestion de projet. Appliqué à la documentation, il répond à quatre questions essentielles.

Modèle RACI appliqué à la documentation : Responsible, Accountable, Consulted, Informed

Les quatre rôles expliqués

Le sigle RACI distingue quatre implications très différentes dans un même document, qu'on confond souvent en pratique. La distinction qui compte le plus est celle entre Responsible (celui qui écrit) et Accountable (celui qui répond de la qualité) : ce sont deux rôles, parfois portés par deux personnes. Parcourez les onglets dans l'ordre, du plus impliqué au moins impliqué.

Qui fait le travail ?

Le Responsible est la personne qui rédige et met à jour le document. C'est elle qui ouvre l'éditeur, tape le contenu, soumet la PR.

Caractéristiques :

Plusieurs personnes peuvent être Responsible
Le Responsible exécute, il ne décide pas seul
Il doit avoir le temps et les compétences

Exemple : Le développeur qui implémente une nouvelle feature est Responsible de la mise à jour du Service Overview.

La règle d'or du RACI

Exemple concret : Service API Payments

Voici comment appliquer le RACI à un service réel :

Document	R (rédige)	A (valide)	C (consulte)	I (informé)
Service Overview	Dev @alice	Tech Lead @bob	Ops @charlie	Support, Produit
Runbook déploiement	Ops @charlie	Tech Lead @bob	Dev @alice	On-call
Runbook incident DB	DBA @diana	Tech Lead @bob	Ops @charlie	On-call
Postmortem	Incident Commander	Tech Lead @bob	Participants	Toute l'équipe, Management
ADR choix techno	Dev @alice	Tech Lead @bob	Archi @eric	Équipe dev

Observations :

Le Tech Lead est Accountable de tous les documents critiques du service
Les Responsible changent selon l'expertise requise
L'équipe On-call est systématiquement informée des runbooks

Le cycle de vie d'un document

Chaque document traverse un cycle prévisible. Comprendre ce cycle aide à définir les responsabilités à chaque étape.

Cycle de vie d'un document : Créer, Review, Publier, Maintenir

Responsabilités par phase

À chaque phase du cycle correspond un rôle RACI précis, et c'est ce qui rend le modèle actionnable plutôt que théorique. Lisez la colonne du milieu comme la réponse à « qui déclenche cette phase ? ». La dernière ligne, Maintenir, est la seule qui se répète indéfiniment dans le temps, d'où le paragraphe d'avertissement qui suit le tableau.

Phase	Qui agit	Ce qu'il fait
Créer	Responsible	Rédige le premier draft, assigne l'owner
Review	Consulted + Accountable	Relecture, feedback, validation
Publier	Responsible	Merge, mise en ligne, notification
Maintenir	Owner (Accountable)	Reviews périodiques, mises à jour

La phase Maintenir est la plus critique et la plus souvent négligée. Un document sans maintenance programmée devient obsolète en quelques mois.

Intégrer la documentation dans la Definition of Done

Le problème du "on documentera après"

Combien de fois avez-vous entendu (ou dit) cette phrase ?

"La feature est prête, on fera la doc la semaine prochaine."

Spoiler : la semaine prochaine n'arrive jamais. Une nouvelle urgence apparaît, et la documentation reste indéfiniment dans les limbes.

La solution : intégrer la documentation dans la Definition of Done.

Qu'est-ce que la Definition of Done ?

La Definition of Done (DoD) est une checklist de critères qui définissent quand un travail est réellement terminé. Elle vient du monde Agile/Scrum mais s'applique à toute méthodologie.

L'idée clé : un travail n'est pas "done" tant que tous les critères ne sont pas remplis, y compris la documentation.

DoD avec documentation intégrée

Voici une Definition of Done enrichie où la documentation n'est pas une étape optionnelle de fin, mais un critère au même titre que les tests. L'ordre compte : la documentation arrive à l'étape 3, avant la validation finale, pour être écrite tant que le contexte est frais dans la tête de l'auteur. Le tableau de l'étape 3 relie chaque type de changement au document précis à toucher, ce qui évite le réflexe « pas d'impact doc ».

Code mergé

La PR est approuvée et fusionnée dans la branche principale.
Tests passent

CI vert : tests unitaires, intégration, e2e selon le projet.

Documentation mise à jour

Selon l'impact de la modification :

Type de changement	Documentation à mettre à jour
Nouvelle feature	Service Overview, README
Changement d'API	API Reference, exemples
Nouvelle procédure ops	Créer un runbook
Modification config	Référentiel de configuration
Changement d'architecture	Diagrammes, ADR si décision majeure

Review documentation effectuée

Quelqu'un d'autre que l'auteur a relu et validé.
Changelog mis à jour

Entrée ajoutée pour la traçabilité.

Template de PR avec checklist documentation

Intégrez cette checklist dans votre template de Pull Request :

## Checklist avant merge

### Code
- [ ] Tests unitaires ajoutés/mis à jour
- [ ] Tests d'intégration passent
- [ ] Code review approuvée

### Documentation
- [ ] Impact documentaire évalué (voir tableau ci-dessous)
- [ ] Documentation mise à jour si nécessaire
- [ ] Review doc effectuée par un pair
- [ ] Changelog mis à jour

### Impact documentaire
<!-- Cochez ce qui s'applique -->
- [ ] Pas d'impact sur la documentation
- [ ] Service Overview mis à jour
- [ ] README mis à jour
- [ ] Runbook créé/modifié
- [ ] API Reference mise à jour
- [ ] Autre : _______________

Qui est responsable de quoi ?

Matrice par type de document

Pour chaque type de document, un owner naturel s'impose presque toujours : la personne ou l'équipe qui connaît le mieux le sujet ou qui s'en sert le plus. La colonne « Raison » est la plus utile à lire, car elle donne le critère de décision transposable à un type de document absent du tableau. Attribuez l'ownership à qui a le contexte, pas à qui a du temps libre.

Type de document	Owner naturel	Raison
Service Overview	Tech Lead du service	Vision globale, décisions d'architecture
Runbook	Équipe Ops / SRE	Utilisateurs principaux en incident
Postmortem	Incident Commander	A coordonné la résolution, connaît le contexte
ADR	Auteur de la décision	Connaît le raisonnement et les alternatives
API Reference	Équipe Dev backend	Connaît le code et les contrats
Guide utilisateur	Product Owner	Connaît les besoins utilisateurs
Onboarding	Engineering Manager	Responsable de l'intégration des nouveaux

Matrice par événement déclencheur

L'ownership par type de document ne suffit pas : il faut aussi savoir quand agir. Cette matrice part de l'événement concret, celui qui survient dans la vie de l'équipe, et indique le geste documentaire attendu, avec le Responsible qui l'exécute et l'Accountable qui le valide. C'est le complément dynamique du tableau précédent : l'un dit qui possède, l'autre dit quand mettre à jour.

Événement	Action documentation	Responsible	Accountable
Nouvelle feature	Créer/màj Service Overview	Dev qui implémente	Tech Lead
Incident résolu	Créer postmortem	Incident Commander	Tech Lead
Nouveau service	Créer Service Overview + runbooks	Équipe du service	Tech Lead
Changement config prod	Màj référentiel	Auteur du changement	Ops Lead
Départ d'un membre	Transférer ownership docs	Partant + successeur	Manager
Refactoring majeur	Màj architecture	Dev qui refactorise	Tech Lead

Mettre en place l'ownership : guide pas à pas

Inventorier la documentation existante

Recensez tout ce qui existe : wiki, Confluence, Google Docs, README, fichiers Markdown éparpillés, notes Notion...

Créez un tableur simple :

Document Emplacement Dernière màj Owner actuel
... ... ... ...

Objectif : avoir une vue complète, même du chaos.
Identifier les documents orphelins

Pour chaque document, posez la question : "Qui est responsable de le maintenir ?"

Si personne ne sait, ou si la réponse est "l'équipe" sans personne nommée, c'est un document orphelin, candidat à l'obsolescence.

Marquez-les dans votre inventaire.
Assigner un owner à chaque document

Règle de choix : l'owner est soit :
- La personne/équipe qui utilise le plus ce document
- La personne qui connaît le mieux le sujet
Documentez l'ownership dans le document lui-même (frontmatter, header, ou section dédiée).
```
---
title: "Runbook : Redémarrage API Gateway"
owner: "@ops-team"
last_review: "2024-11-15"
next_review: "2025-02-15"
---
```

Document	Emplacement	Dernière màj	Owner actuel
...	...	...	...

Définir les cadences de review

Chaque type de document a une fréquence de relecture adaptée :

Type	Fréquence review	Déclencheur additionnel
Runbooks critiques	Mensuelle	Après chaque utilisation
Service Overviews	Trimestrielle	Après changement majeur
Référentiels	Trimestrielle	Arrivées/départs
ADR	Jamais	Immuables (nouvelle ADR si révision)
Postmortems	Jamais	Archives historiques

Automatiser les rappels

Ne comptez pas sur la mémoire humaine. Mettez en place :
- Calendrier partagé : événements récurrents pour les reviews
- Bot Slack/Teams : rappels automatiques aux owners
- CI/CD : vérification de la date de dernière mise à jour
Fenêtre de terminal
```
# Exemple : script qui liste les docs à reviewer
find docs/ -name "*.md" -mtime +90 -print
```
Intégrer dans les processus existants
- Ajoutez la checklist doc dans votre template de PR
- Incluez la review doc dans vos sprints
- Mentionnez la doc dans vos rétrospectives

Automatiser l'ownership avec CODEOWNERS

Plutôt que de tenir l'ownership dans un tableau qui se périme, inscrivez-le dans le dépôt. Le fichier CODEOWNERS (GitHub comme GitLab) associe des chemins à leurs responsables, et demande automatiquement leur review sur chaque pull request qui touche « leurs » fichiers. C'est l'ownership rendu exécutable.

Le fichier se place à la racine, dans .github/ ou docs/. Chaque ligne associe un motif de fichier à un ou plusieurs owners :

# .github/CODEOWNERS
# Toute la documentation est revue par l'équipe doc
/docs/                 @mon-org/equipe-doc

# Les runbooks ont en plus un owner SRE
/docs/runbooks/        @mon-org/equipe-doc @alice

# Un domaine technique précis
/docs/securite/        @bob

Trois règles à retenir, vérifiées sur la documentation officielle :

Les owners d'un même motif doivent être sur la même ligne (sinon seul le dernier compte).
En cas de motifs multiples, le dernier motif correspondant l'emporte.
Un owner doit avoir un accès en écriture au dépôt ; sur une draft PR, la review n'est pas demandée tant qu'elle reste en brouillon.

Transférer l'ownership lors d'un départ

Quand quelqu'un quitte l'équipe (départ, changement de poste, congé long), ses documents doivent être explicitement transférés. Sinon, ils deviennent orphelins.

Checklist de transfert

Un transfert réussi se prépare, il ne s'improvise pas le dernier jour. Le premier onglet donne le déroulé chronologique, de deux semaines avant le départ jusqu'aux actions post-départ ; le second fournit un modèle de compte rendu à copier. Le fil conducteur : chaque document dont le partant est owner doit avoir un successeur nommé et avoir fait l'objet d'une session de passation avant qu'il ne parte.

Avant le départ
Template handover

2 semaines avant (minimum) :

Lister tous les documents dont la personne est owner
Identifier un nouvel owner pour chaque document
Planifier les sessions de transfert (30 min par doc critique)
Vérifier que le nouvel owner a les accès nécessaires

1 semaine avant :

Sessions de transfert effectuées
Le nouvel owner a relu et validé sa compréhension
Métadonnées mises à jour (owner dans les docs)
Nouvel owner ajouté aux canaux de notification

# Transfert documentation : [Nom du partant]

**Date de départ :** YYYY-MM-DD
**Manager :** @manager

## Documents transférés

| Document | Ancien owner | Nouvel owner | Session | Statut |
|----------|--------------|--------------|---------|--------|
| Service Overview API Auth | @partant | @alice | 2024-01-15 | ✅ |
| Runbook déploiement | @partant | @bob | 2024-01-16 | ✅ |
| ADR-042 Choix Redis | @partant | @charlie | - | ✅ (pas de session, ADR stable) |

## Sessions de transfert planifiées

- [x] 2024-01-15 14h : Service Overview (1h avec @alice)
- [x] 2024-01-16 10h : Runbooks (1h30 avec @bob)
- [ ] 2024-01-17 14h : Référentiel config (30min avec @charlie)

## Actions post-départ

- [ ] Supprimer @partant des listes d'owners
- [ ] Vérifier les accès des nouveaux owners
- [ ] Notifier les équipes concernées
- [ ] Archiver les notes de handover

Mesurer l'efficacité de l'ownership

Comment savoir si votre système d'ownership fonctionne ?

KPIs à suivre

Ces cinq indicateurs transforment l'impression diffuse « notre doc est à jour » en chiffres vérifiables. Deux colonnes se lisent ensemble : l'objectif fixe la cible, le signal d'alerte marque le seuil où il faut agir. Commencez par le taux de docs orphelins et le pourcentage de docs avec owner : ce sont les deux qui prédisent le mieux l'obsolescence à venir.

Métrique	Calcul	Objectif	Signal d'alerte
% docs avec owner	Docs avec owner / Total docs	> 95%	< 80%
Âge moyen dernière màj	Moyenne des dates de màj	< 6 mois	> 1 an
Docs màj post-incident	Docs màj dans 7j après incident / Total incidents	100%	< 50%
Temps pour trouver l'owner	Temps moyen pour identifier qui contacter	< 1 min	"Faut demander"
Taux de docs orphelins	Docs sans owner / Total docs	0%	> 5%

Audit trimestriel

Programmez un audit léger chaque trimestre :

## Audit documentation Q1 2025

### Inventaire
- Total documents : 47
- Avec owner identifié : 45 (96%)
- Sans owner (orphelins) : 2

### Documents orphelins identifiés
1. `wiki/legacy/old-deploy-process.md` : à archiver
2. `docs/api/deprecated-v1.md` : à supprimer (API dépréciée depuis 2 ans)

### Fraîcheur
- Mis à jour < 3 mois : 28 (60%)
- Mis à jour 3-6 mois : 12 (25%)
- Mis à jour > 6 mois : 7 (15%) : à reviewer

### Actions
- [ ] Archiver les 2 docs orphelins
- [ ] Planifier review des 7 docs > 6 mois
- [ ] Rappeler la DoD à l'équipe (2 PRs sans màj doc ce trimestre)

Anti-patterns à éviter

Ces six erreurs reviennent dans presque toutes les tentatives d'ownership ratées. La plus répandue est la première, « l'équipe est owner » : une responsabilité partagée par tous n'est portée par personne. Traitez le tableau comme une grille d'auto-diagnostic, ligne par ligne, en confrontant chaque anti-pattern à vos propres pratiques ; la colonne de droite donne la correction directe.

Anti-pattern	Pourquoi c'est problématique	Solution
"L'équipe est owner"	Responsabilité diffuse = pas de responsabilité	Nommer une personne (qui peut déléguer)
Owner = créateur original	Il a peut-être changé d'équipe depuis	Owner = utilisateur principal actuel
Ownership non documenté	"Je crois que c'est Jean..."	Owner écrit dans le document
Pas de backup	Owner en vacances = doc bloquée	Désigner owner + backup
Owner sans temps	Responsable mais jamais de temps alloué	Inclure la maintenance doc dans la charge
Ownership informel	"Tout le monde sait que c'est moi"	Formaliser par écrit

Checklist récapitulative

Avant de considérer votre système d'ownership comme opérationnel :

Chaque document critique a un owner nommé et documenté
La DoD de l'équipe inclut la documentation
Les templates de PR incluent la checklist doc
Les cadences de review sont définies par type de document
Un processus de transfert existe pour les départs
Des rappels automatiques sont en place
Un audit trimestriel est programmé

À retenir

Sans owner nommé, un document devient orphelin et se périme : Google le formule comme « les documents sans owner deviennent difficiles à maintenir ».
Le modèle RACI clarifie les rôles, avec un seul responsable (Accountable) par document.
CODEOWNERS rend l'ownership exécutable : review automatiquement demandée à l'owner sur chaque PR touchant ses fichiers.
Privilégiez une équipe comme owner principal : un départ ne casse pas la chaîne.
Intégrez « documentation à jour » dans la Definition of Done pour écrire pendant que c'est frais.
Transférez explicitement l'ownership lors d'un départ et auditez régulièrement les orphelins.

Prochaines étapes

L'ownership définit qui maintient. Mais comment s'assurer que la maintenance est effectivement faite ?

Reviews et fraîcheur Mettre en place les cycles de review et automatiser les rappels.

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

Références

Google SRE Book - Eliminating Toil, La documentation claire réduit le toil opérationnel
Atlassian - Definition of Done, Intégrer la qualité dans la DoD
RACI Matrix Explained, Le modèle RACI en gestion de projet