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 :

1. L’équipe Plateforme crée un runbook pour le service de paiement
2. Trois mois plus tard, l’équipe Checkout modifie la configuration du service
3. L’équipe Plateforme n’est pas informée — le runbook reste inchangé
4. Un incident survient à 3h du matin. L’astreinte suit le runbook obsolète
5. 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

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

L’analogie du jardin partagé

Pour comprendre l’importance de l’ownership, pensez à un jardin communautaire.

Sans règles définies : personne ne sait qui doit arroser, qui désherbe, qui taille. Résultat prévisible : les mauvaises herbes envahissent, les plantes meurent, le jardin devient une friche.

Avec des parcelles assignées : chaque jardinier connaît sa zone de responsabilité. Il peut demander de l’aide, échanger des conseils, mais il sait que sa parcelle lui appartient. Le jardin prospère.

La documentation fonctionne exactement de la même façon. Sans ownership clair, elle se dégrade naturellement — c’est une loi de l’entropie informationnelle.

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.

Les quatre rôles expliqués

R - Responsible

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.

A - Accountable

Qui est le garant final ?

L’Accountable est la personne qui valide que le travail est fait correctement. C’est le décideur final, celui qui approuve ou refuse.

Caractéristiques :

• Un seul Accountable par document (règle non négociable)
• Responsable même s’il ne fait pas le travail lui-même
• Peut déléguer l’exécution, pas la responsabilité

Exemple : Le Tech Lead est Accountable du Service Overview — il valide que le contenu est correct et complet.

C - Consulted

Qui apporte son expertise ?

Le Consulted est sollicité avant la publication pour donner un avis. C’est une communication bidirectionnelle : on lui pose des questions, il répond.

Caractéristiques :

• Expertise technique ou métier
• Son avis est sollicité, pas imposé
• Peut bloquer si problème majeur identifié

Exemple : L’équipe Ops est Consulted pour les runbooks — elle vérifie que les procédures sont réalistes en production.

I - Informed

Qui doit être notifié ?

L’Informed reçoit l’information après la publication ou mise à jour. C’est une communication unidirectionnelle : on l’informe, il n’a pas besoin de répondre.

Caractéristiques :

• Besoin de savoir, pas de décider
• Notification automatisable
• Peut être un groupe large

Exemple : L’équipe Support est Informed des mises à jour de la FAQ produit — elle doit connaître les réponses actuelles.

La règle d’or du RACI

Règle non négociable

1 document = 1 seul Accountable

Si deux personnes sont “accountable”, aucune ne l’est vraiment. C’est la recette garantie de l’obsolescence : chacun pense que l’autre s’en occupe.

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.

Responsabilités par phase

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

1. Code mergé

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

2. Tests passent

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

3. 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

4. Review documentation effectuée

   Quelqu’un d’autre que l’auteur a relu et validé.

5. 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 : _______________

Automatisation

Configurez votre CI pour vérifier que la checklist est complétée avant d’autoriser le merge. Des outils comme danger.js ou des GitHub Actions personnalisées peuvent automatiser cette vérification.

Qui est responsable de quoi ?

Matrice par type de document

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

É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

1. 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.

2. 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.

3. 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"
   ---

4. 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

5. 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

   # Exemple : script qui liste les docs à reviewer
   find docs/ -name "*.md" -mtime +90 -print

6. 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

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

Avant le départ

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

Template handover

# 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

Piège fréquent

Ne pas attendre le dernier jour. Le transfert de connaissances demande du temps. Si la personne part dans 3 jours et que rien n’est prévu, les documents seront de facto orphelins.

Mesurer l’efficacité de l’ownership

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

KPIs à suivre

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

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é

Pour aller plus loin

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