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.
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.
Le guide Comment intégrer des experts métier très occupés dans un projet web ? aide à extraire ces règles sans épuiser les sachants.
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.
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
Le guide Documenter un legacy avant le départ des sachants aide à capturer les savoirs critiques.
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 permettent à plusieurs personnes d’agir sans repartir de zéro.
Journal de décisions, règles métier, flux, données, runbook, onboarding, dette et incidents doivent rester vivants, reliés aux décisions et utiles dans le quotidien.
Dawap accompagne les projets d’application métier sur mesure et de reprise d’existant avec documentation vivante, transmission, audit, architecture et organisation run pour réduire la dépendance humaine sans ralentir les équipes.
