Documentation first : pourquoi les agences ne le font pas et pourquoi ça tient dans la durée

Ce que la plupart des projets IT livrent (et ce qu'ils ne livrent pas)

À la fin d'un projet IT standard, le client reçoit un système fonctionnel. Il reçoit du code, des fonctionnalités, des interfaces. Ce qu'il ne reçoit pas, dans la grande majorité des cas, c'est la raison pour laquelle ce système a été construit de cette façon et pas d'une autre. Pourquoi cette table de base de données a ces colonnes plutôt que d'autres. Pourquoi cette règle métier a été encodée ainsi. Pourquoi cette architecture permet de connecter facilement tel futur module et pas tel autre.

Ces informations ne sont pas dans le code. Elles sont dans la tête des développeurs qui ont construit le système. Quand ces développeurs partent, la moitié de la valeur du projet part avec eux. Le nouveau prestataire ou l'équipe interne qui reprend le travail six mois plus tard passera des semaines à reconstruire par rétro-ingénierie ce que quelques pages de documentation auraient rendu immédiatement lisible.

Ce n'est pas une fatalité. C'est un choix fait très tôt dans le projet, souvent implicitement : documenter ou ne pas documenter au fur et à mesure. Les prestataires qui documentent ne sont pas plus lents que les autres. Ils ont simplement intégré que leur livrable ne s'arrête pas à la mise en production.

Pourquoi la documentation est systématiquement sacrifiée

La documentation ne se vend pas. C'est la raison principale. Sur un devis, la ligne « documentation technique et fonctionnelle » est la première à être négociée à la baisse, voire supprimée pour rester compétitif. Un client qui compare deux offres voit une fonctionnalité livrée, pas le document qui explique pourquoi l'architecture a été conçue ainsi. La différence n'est visible que douze à dix-huit mois plus tard, quand il voudra faire évoluer le système, changer de prestataire, ou passer un audit interne.

La deuxième raison est organisationnelle. Documenter en temps réel impose une discipline que beaucoup d'équipes n'ont pas : écrire au moment où la décision est prise, pas après. Cette discipline suppose que la documentation soit considérée comme une partie intégrante du travail, pas comme une tâche annexe qu'on remettra « à la fin du sprint ». En pratique, la fin du sprint arrive, la prochaine feature commence, et la documentation reste vide. Ce n'est pas un manque de bonne volonté, c'est un manque de processus.

La troisième raison est plus subtile. Documenter correctement suppose de comprendre les décisions que l'on prend. Un développeur qui « vibe code » avec une IA sur une feature entière prend des décisions architecturales sans toujours en avoir conscience. Il ne peut pas documenter ce qu'il n'a pas délibérément décidé. La documentation first est incompatible avec le développement au fil de l'eau. Elle suppose un cadrage préalable assez solide pour que chaque décision de code soit intentionnelle.

Pour comprendre pourquoi le cadrage préalable conditionne la documentation : comment structurer un back-office commercial sans refondre tout votre SI.

Ce que la documentation first change concrètement

La documentation first change trois choses mesurables sur la durée d'un projet : la capacité de reprise par une nouvelle équipe, la vitesse d'évolution des fonctionnalités existantes, et la résistance aux audits extérieurs.

Sur la reprise, la différence est immédiate. Une équipe interne qui reprend un code documenté comprend en quelques jours ce qui lui aurait pris plusieurs semaines sans documentation. Chaque décision d'architecture est expliquée, chaque règle métier est rendue explicite, chaque contrainte identifiée en amont est notée avec sa raison. La courbe d'apprentissage passe de huit à douze semaines à deux à trois semaines. Ce n'est pas une économie marginale : c'est la différence entre un projet que l'entreprise peut reprendre en main et un projet dont elle reste dépendante du prestataire initial.

Sur les évolutions, la documentation permet de ne pas tout re-comprendre à chaque modification. Quand on veut ajouter une règle métier à un module existant, on sait précisément ce que cette règle viendra modifier, quels objets elle touchera, quels scénarios elle affectera. Sans documentation, chaque évolution est une exploration dont on ne maîtrise pas les effets de bord avant de les avoir constatés en production.

L'audit comme test de résistance de la documentation

Il y a un test particulièrement révélateur de la qualité de la documentation d'un projet : un audit externe. Pas un audit de code, un audit de pratiques, du type que font les cabinets de contrôle dans les groupes avec des filiales. La question posée est simple : est-ce que ce système est compréhensible par quelqu'un qui ne l'a pas construit ? Est-ce que les décisions structurantes sont traçables ? Est-ce que les règles métier sont explicitées ?

« Un des points que j'ai beaucoup aimé, c'est quand Olivier nous a expliqué que sur cet audit de 2026, ils avaient pu rassurer le cabinet d'audit du groupe en leur montrant le travail qu'on faisait, la documentation qu'on avait créée — vu qu'on a une approche de documentation first — et que ça avait vraiment permis de faire le jour et la nuit dans la manière de livrer cet audit. »

L'ETI dont il est question ici est une filiale française d'un groupe suisse, soumise à des audits internes annuels. L'audit 2024 avait été décevant. Pas parce que le projet était techniquement défaillant, mais parce que personne ne pouvait expliquer clairement les décisions prises, les règles appliquées, l'architecture en place.L'audit 2026, réalisé sur un projet documenté en temps réel, a produit un résultat radicalement différent. Le cabinet externe a été rassuré. Le DSI a pu répondre à chaque question sur les choix d'architecture en renvoyant vers un document qui expliquait non seulement quoi mais pourquoi. La documentation est devenue un livrable de groupe à part entière, pas seulement un accessoire du projet technique.

Comment exiger de la documentation sans freiner le projet

Exiger de la documentation ne ralentit pas un projet bien cadré.Cela ralentit un projet mal cadré, parce que documenter une décision qu'on n'a pas délibérément prise est difficile. Si les règles métier ont été explicitées avant le développement, si le modèle de données a été posé avant que la première ligne de code soit écrite, la documentation devient naturelle : elle décrit ce qui a été décidé, pas ce qui a été découvert en codant.

La façon la plus efficace d'exiger de la documentation est de l'intégrer dans les critères de livraison, pas de l'ajouter comme condition après coup. Chaque décision d'architecture documentée dans la semaine où elle est prise. Chaque règle métier encodée accompagnée d'une explication de pourquoi cette règle existe et dans quel cas elle s'applique. Chaque objet métier du modèle de données décrit avec ses relations et ses contraintes. Ce n'est pas un travail additionnelsi le prestataire est en mode documentation first dès le démarrage : c'est le travail normal, réalisé dans l'ordre.

La question à poser à un prestataire n'est pas « documentez-vous ? ». Elle est « pouvez-vous me montrer un livrable de documentation sur un projet précédent ? » Si le prestataire ne peut pas répondre avec un exemple concret, la documentation ne fait pas partie de sa pratique courante, quel que soit ce qu'il dit sur ce sujet dans son devis.

Le cas BKW illustre un point important : la documentation first n'est pas qu'une bonne pratique technique. C'est un levier stratégique pour une ETI qui veut reprendre la main sur son SI, réduire sa dépendance au prestataire externe, et répondre aux exigences d'un groupe qui audite ses filiales. La valeur ne se voit pas à la livraison. Elle se voit douze mois plus tard, quand l'équipe interne peut faire évoluer le système sans repartir de zéro, et quand l'auditeur repart rassuré. Sur ce point, voir aussi comment migrer son ERP en PME sans big bang.