Beaucoup d’équipes disent avoir de la documentation. Mais quand une personne clé est absente, elles ne savent toujours pas diagnostiquer, arbitrer, corriger ou expliquer le logiciel.
Le problème ne vient pas toujours de la quantité de documents. Il vient souvent du fait qu’ils ne servent pas à agir. Ils décrivent un état, mais n’aident pas à prendre une décision ou à reprendre un sujet.
Sur une application métier sur mesure, les documents de référence doivent réduire la dépendance humaine en permettant à plusieurs personnes de comprendre les règles, le run, les risques et les choix passés.
Le vrai enjeu est de constituer un petit système de preuves maintenu au rythme du produit : décisions datées, règles testables, carte des flux, procédures de reprise et accès maîtrisés. Dans une démarche de développement web sur mesure, cette référence doit permettre à une personne compétente mais nouvelle de résoudre un cas réel sans dépendre d’une mémoire individuelle.
Pourquoi documenter ne suffit pas
Une documentation utile ne cherche pas à tout dire. Elle cherche à rendre le système reprenable. Elle répond aux questions qui bloquent vraiment : pourquoi cette règle existe, que faire si ça casse, qui peut trancher, quel risque est connu.
Un document qui n’est jamais relu, jamais corrigé et jamais utilisé dans les décisions devient vite une archive morte.
Le document doit être relié à un usage
Chaque document doit servir à au moins une action : onboarder, diagnostiquer, corriger, arbitrer, tester, déployer, supporter ou expliquer.
Le bon niveau de détail dépend du risque
Un module critique, un traitement financier, une règle de droits ou une reprise manuelle mérite plus de précision qu’un écran secondaire peu utilisé.
Le journal de décisions
Le journal de décisions est souvent le document le plus rentable. Il explique ce qui a été choisi, pourquoi, par qui, avec quelles alternatives et quels risques acceptés.
Ce qu’il doit contenir
Date, contexte, options comparées, décision retenue, raison, impact, personne responsable et critères de réouverture. Sans ces éléments, la décision sera rediscutée plus tard comme si elle n’avait jamais existé.
Quand le mettre à jour
À chaque arbitrage durable : architecture, règle métier, dette acceptée, compromis de performance, choix de données, priorité produit ou comportement support.
Les règles métier et cas limites
Les règles métier doivent être compréhensibles par les métiers et par la technique. Elles doivent expliquer les statuts, calculs, validations, droits, exceptions et cas où la règle ne s’applique pas.
Documenter les exceptions
Les exceptions sont souvent ce qui rend le logiciel fragile. Elles doivent être nommées, justifiées et reliées à des exemples réels.
Relier règle et écran
Une règle doit pouvoir être retrouvée depuis les écrans, traitements, exports ou alertes qu’elle influence.
Pour extraire ces règles sans épuiser les sachants, appuyez-vous sur Comment intégrer des experts métier très occupés dans un projet web ?.
Architecture, flux et données
La cartographie technique doit permettre de répondre vite à trois questions : quelles données circulent, quels systèmes dépendent les uns des autres et quelles zones sont sensibles.
Le schéma des flux
Il doit montrer les entrées, sorties, APIs, fichiers, traitements planifiés, systèmes tiers, responsabilités et erreurs connues.
La source de vérité
Pour chaque donnée critique, l’équipe doit savoir où elle naît, où elle est modifiée, où elle est lue et qui peut la corriger.
Les zones à ne pas modifier sans revue
Certains modules, tables ou traitements doivent être identifiés comme sensibles. Cela évite qu’un nouvel arrivant les modifie sans contexte.
Runbook, incidents et procédures de reprise
Le runbook explique quoi faire quand le système ne se comporte pas comme prévu. C’est l’un des meilleurs moyens de réduire la dépendance à une personne qui “sait quoi faire”.
Les procédures utiles
Diagnostic, vérification de logs, reprise d’un traitement, rollback, relance contrôlée, escalade, communication support et validation métier.
Les incidents passés
Chaque incident significatif doit laisser une fiche : symptôme, cause, impact, correction, contournement, décision et prévention.
Le guide Comment gérer l’après go-live entre équipe projet et équipe run ? complète ce point côté exploitation.
Guide d’onboarding et accès
Un bon guide d’onboarding permet à une nouvelle personne de comprendre le produit, installer son environnement, obtenir les bons accès et traiter un premier sujet sans dépendre d’un sachant pendant plusieurs jours.
Ce qu’il doit contenir
Vue d’ensemble, interlocuteurs, accès, installation, conventions, premiers tickets recommandés, zones sensibles, circuits de validation et documentation à lire.
Le tester avec chaque nouvel arrivant
Chaque onboarding révèle les trous de documentation. Il faut les corriger immédiatement, sinon le document perd sa valeur.
Le guide Onboarding d’un nouveau prestataire sur projet legacy montre comment structurer cette entrée.
Dette connue et risques acceptés
La dette non documentée devient une surprise. La dette documentée devient un risque pilotable.
Nommer la dette sans dramatiser
Il faut décrire la zone, le risque, l’impact, les symptômes possibles, les raisons du maintien et les conditions de traitement.
Relier la dette aux décisions produit
Une dette technique devient prioritaire quand elle bloque une évolution, crée des incidents, ralentit le support ou expose la donnée.
Comment garder ces documents vivants
Un document de référence doit avoir un propriétaire, un rythme de revue et un déclencheur de mise à jour.
Mettre à jour au moment de la décision
La mise à jour doit être faite quand le contexte est frais. Attendre la fin du projet produit souvent des documents incomplets.
Faire relire par deux profils
Une personne technique et une personne métier doivent pouvoir comprendre les documents qui relient règle, code et exploitation.
Supprimer ce qui ne sert plus
Une documentation trop pleine devient inutilisable. Les pages obsolètes doivent être archivées ou retirées.
Pour qui constituer un socle documentaire prioritaire
Le besoin devient urgent lorsqu’un logiciel porte une facturation, des droits, une production quotidienne ou une relation client et qu’une seule personne sait expliquer ses exceptions. Il concerne aussi les équipes qui changent de prestataire, préparent une migration ou absorbent une croissance rapide. Un prototype temporaire peut garder une trace plus légère ; un produit critique exige des documents éprouvés par l’usage.
Une petite équipe doit documenter le risque, pas tout le code
Deux développeurs ne peuvent pas maintenir un wiki exhaustif. Ils commencent par les zones dont l’ignorance empêcherait de livrer ou restaurer : source de vérité, procédure de déploiement, sauvegardes, secrets, règles irréversibles et contacts externes. Une fonction lisible dans le code n’a pas besoin d’une paraphrase ; une contrainte héritée d’un contrat partenaire mérite une décision datée.
Une organisation multi-prestataires documente les coutures
Lorsque plusieurs sociétés interviennent, les zones entre contrats deviennent les plus fragiles. La référence décrit qui émet la donnée, qui la valide, qui observe l’échec et qui réconcilie. Un schéma d’architecture sans propriétaire ni seuil d’escalade reste décoratif. Le premier signal faible apparaît lorsque chaque acteur possède sa procédure, mais qu’aucune ne couvre le parcours complet.
Un legacy exige la différence entre constat et intention
Le document sépare ce qui fonctionne aujourd’hui de ce qui était prévu. Un diagramme idéal peut guider une refonte, mais ne doit pas masquer une table alimentée manuellement ou un traitement désactivé depuis un incident. Cette distinction empêche une équipe entrante de prendre une cible d’architecture pour une description de production.
Tester la documentation pendant un incident simulé
Cas concret : l’export comptable n’est pas produit
Une application génère chaque nuit un export envoyé au logiciel comptable. La personne qui avait construit le traitement est absente. L’exercice donne à un développeur qui ne connaît pas le module un identifiant de lot, un horaire et l’accès en lecture. Il doit retrouver le worker, vérifier la dernière exécution, identifier les lignes rejetées et expliquer si une relance créerait un doublon.
Le runbook indique la commande, mais l’exercice révèle qu’il ne précise ni la source de vérité ni le contrôle après reprise. Le développeur pourrait relancer le lot entier et dupliquer des écritures déjà reçues. L’équipe complète alors la procédure avec la clé d’idempotence, la requête de vérification, le seuil d’écart qui impose une validation comptable et la personne autorisée à déclencher la reprise.
Le scénario est réussi lorsque le diagnostic, la décision et la preuve finale sont reproductibles. Un statut technique vert ne suffit pas : le nombre de lignes côté application doit correspondre au fichier accepté, et les rejets doivent garder un propriétaire. Si l’exercice dépasse le délai compatible avec la clôture, alors la priorité reste la documentation et l’observabilité, pas une nouvelle fonctionnalité.
Mesurer le temps de compréhension
Un document utile réduit le nombre d’hypothèses et d’interruptions. L’équipe peut suivre le temps nécessaire pour retrouver la procédure, localiser la donnée et obtenir la décision, sans transformer cette durée en objectif rigide. Une hausse signale souvent un index obsolète, des liens cassés ou des responsabilités devenues floues avant même qu’un incident grave ne le montre.
- La page indique son propriétaire, sa date de dernière vérification et l’événement qui impose une mise à jour.
- Les entrées, sorties, dépendances et droits requis sont nommés avec leur source opposable.
- La procédure comprend le contrôle du résultat et le repli, pas seulement la commande à exécuter.
- Une personne non auteure a rejoué le scénario sur un environnement sûr et corrigé les ambiguïtés.
Erreurs fréquentes qui fabriquent des archives mortes
Générer une documentation exhaustive avant la livraison
Une grande campagne produit souvent des pages cohérentes au jour de leur création, puis déconnectées du cycle de changement. Il vaut mieux documenter les décisions et les opérations critiques dans la même revue que le code. La définition de terminé inclut la mise à jour lorsque le comportement, la dépendance ou la procédure de reprise change.
Confondre auto-documentation du code et connaissance métier
Des noms clairs et des tests expliquent comment le logiciel calcule. Ils ne disent pas toujours pourquoi une exception existe, qui peut l’autoriser ou quel engagement elle protège. La règle métier conserve un exemple accepté, un contre-exemple, la source de décision et le critère qui permet de la retirer.
Dupliquer la même vérité dans plusieurs outils
Une procédure copiée dans le wiki, le ticket et un document partagé diverge rapidement. Chaque type d’information possède un emplacement canonique ; les autres supports pointent vers lui. Si une copie hors ligne est nécessaire pour la continuité, elle est générée et datée plutôt que modifiée séparément.
La règle vaut également pour les schémas et les exemples de payload. Une spécification OpenAPI générée par la chaîne de livraison reste la référence du contrat ; le guide métier explique les choix et renvoie vers sa version publiée. Si un exemple doit être corrigé à trois endroits, la prochaine modification créera presque certainement une contradiction. Une vérification automatique des liens et une revue sur les changements sensibles réduisent ce risque sans transformer la documentation en projet séparé.
Écrire pour l’auteur au lieu du prochain lecteur
Des expressions comme « relancer si besoin » ou « vérifier les données » cachent précisément la décision attendue. Le document nomme la requête, le résultat normal, le seuil d’alerte et l’interlocuteur. Une relecture par une personne nouvelle révèle ces implicites plus sûrement qu’une validation formelle par l’auteur.
En réalité, supprimer une page peut améliorer la transmission. Une archive ambiguë augmente le coût caché du diagnostic en proposant plusieurs vérités concurrentes. La contre-intuition consiste à réduire le volume documentaire tout en augmentant les exercices de reprise : moins de pages, mais davantage de preuves qu’elles permettent vraiment d’agir.
Plan d’action pour construire la référence en quatre semaines
Semaine 1 : inventorier les décisions et opérations critiques
L’équipe liste dix questions qui bloqueraient une personne nouvelle : comment livrer, restaurer, renouveler un secret, expliquer un calcul, suivre une intégration ou reprendre un lot. Elle associe chaque réponse à une source existante et un propriétaire. Les absences sont classées selon l’impact client, données, sécurité et continuité.
Semaine 2 : produire le socle minimal
Le socle comprend un index, une carte des systèmes, un journal de décisions, les règles métier sensibles, un guide d’accès et les runbooks prioritaires. Chaque page précise l’entrée, la sortie, les dépendances, les responsabilités et le seuil de repli. La journalisation ou le monitoring nécessaires sont liés directement à la procédure.
Pour les données, la référence nomme les identifiants, la source de vérité, la durée de conservation et les transformations importantes. Pour les accès, elle décrit le rôle attendu et le canal d’attribution sans recopier aucun secret. Pour les intégrations, elle relie version de contrat, authentification, timeout, reprise et propriétaire. Ce niveau de détail donne au backend, au support et au métier une base commune tout en laissant le code documenter l’implémentation locale.
Semaine 3 : rejouer deux scénarios
Une personne non auteure exécute un déploiement contrôlé et diagnostique un incident connu sur un environnement isolé. Elle note chaque information manquante, chaque accès indisponible et chaque décision qui exige une consigne orale. Le responsable corrige le document avant de modifier l’outil ou d’ajouter une nouvelle page.
Le premier scénario vérifie une opération courante, par exemple publier une version et contrôler la sortie. Le second provoque une dépendance indisponible, un message redélivré ou une restauration partielle. L’exercice documente le seuil d’arrêt, la journalisation consultée, la responsabilité de l’arbitrage et le repli exécuté. Si la preuve finale ne permet pas de comparer l’état avant et après, le runbook reste incomplet même si la commande technique a réussi.
Semaine 4 : brancher la maintenance sur le delivery
Les modèles de ticket et de revue demandent si la décision, le flux, la règle ou le runbook change. Une vérification trimestrielle cible les documents critiques, mais l’entretien principal reste événementiel : modification du contrat API, incident, arrivée d’un prestataire ou migration. Si une page n’a ni propriétaire ni usage identifié, elle est archivée.
Le responsable documentaire ne réécrit pas seul les pages techniques. Il anime la règle de maintenance, suit les références critiques et facilite les exercices. Le développeur modifie le contrat ou le runbook avec le code ; le métier valide les règles et leurs exemples ; le support corrige les étapes qui échouent en situation réelle. Cette responsabilité distribuée empêche le wiki de devenir le produit isolé d’une personne.
Un tableau minimal suit les documents sans propriétaire, les scénarios jamais rejoués et les pages liées à un incident récent. Le seuil d’intervention doit rester proportionné : une procédure de restauration non vérifiée bloque une mise en production sensible, tandis qu’un schéma d’écran obsolète peut attendre la prochaine évolution. Le comité arbitre ainsi une dette concrète plutôt qu’un pourcentage abstrait de documentation à jour.
- Commencer par les opérations irréversibles et les décisions impossibles à déduire du code.
- Désigner un propriétaire et une source canonique pour chaque référence conservée.
- Tester les documents avec un lecteur neuf et un scénario qui peut réellement échouer.
- Différer l’exhaustivité tant que déploiement, restauration, données et règles sensibles ne sont pas reprenables.
Guides complémentaires pour réduire la dépendance
Ces guides prolongent le sujet sur la transmission, l’onboarding, le legacy et la maîtrise projet.
Transmettre la connaissance
Le guide Transmettre la connaissance d’un logiciel interne à plusieurs personnes donne la méthode globale.
Documenter le legacy
Pour capturer les savoirs critiques, appuyez-vous sur Documenter un legacy avant le départ des sachants.
Onboarder un prestataire
Le guide Onboarding d’un nouveau prestataire sur projet legacy transforme les documents en parcours d’entrée.
Garder la maîtrise
Le guide Garder la maîtrise avec une forte sous-traitance relie documentation et ownership.
Conclusion : un bon document permet d’agir
Les documents de référence utiles ne cherchent pas à remplacer les personnes. Ils rendent une décision, un diagnostic et une reprise accessibles à plusieurs personnes sans les obliger à reconstruire tout l’historique.
Le journal de décisions, les règles métier, la carte des flux et les runbooks forment le noyau. Leur valeur se prouve lorsqu’un lecteur nouveau réussit un scénario réel avec les bons droits, les bons contrôles et une sortie observable.
La priorité va aux zones dont l’ignorance bloque une restauration, expose une donnée ou change un engagement client. Une documentation exhaustive peut attendre ; une procédure critique jamais rejouée ou une règle connue d’une seule personne ne le peut pas.
Dawap peut auditer ce socle, organiser les exercices de reprise et intégrer son entretien au delivery dans le cadre d’un accompagnement en développement web sur mesure, afin de réduire la dépendance humaine sans ralentir l’évolution du produit.
