La documentation : une dépense ou un investissement ?
Dans beaucoup de projets logiciels, la documentation fait l’objet de deux critiques opposées.
Dans certaines organisations, elle est considérée comme une contrainte : les équipes produisent des documents parce qu’un processus, une méthode ou une gouvernance l’impose, sans toujours savoir qui les utilisera.
Dans d’autres, la priorité donnée aux délais conduit à réduire la documentation au minimum. Quelques mois ou quelques années plus tard, lorsqu’il faut maintenir ou faire évoluer l’application, les équipes passent alors beaucoup de temps à comprendre son fonctionnement.
Pour une DSI, la question n’est donc pas : faut-il documenter ?
Elle est plutôt : quel niveau de documentation est économiquement justifié compte tenu du cycle de vie de l’application ?
COCOMO II apporte sur ce point un éclairage particulièrement intéressant.
Ce que mesure le facteur « Documentation adaptée aux besoins du cycle de vie »
Le facteur DOCU (Documentation Match to Life-Cycle Needs) mesure l’adéquation entre la documentation produite et les besoins réels du logiciel pendant son cycle de vie.
Ce facteur est issu du modèle international COCOMO II, utilisé depuis de nombreuses années pour l’estimation des projets logiciels.
L’idée importante est que COCOMO II ne considère pas qu’une documentation abondante est nécessairement meilleure.
Le niveau de référence correspond à une documentation dimensionnée aux besoins du cycle de vie.
Deux situations peuvent donc être défavorables :
- ne pas suffisamment documenter ;
- produire une documentation excessive par rapport aux besoins réels.
La première peut créer une dette pour les phases futures. La seconde consomme inutilement des ressources pendant le développement.
Les différents niveaux
COCOMO II distingue cinq niveaux applicables :
| Niveau | Situation |
| Très faible | De nombreux besoins du cycle de vie ne sont pas couverts |
| Faible | Certains besoins du cycle de vie ne sont pas couverts |
| Nominal | Documentation adaptée aux besoins du cycle de vie |
| Élevé | Documentation excessive par rapport aux besoins |
| Très élevé | Documentation très excessive par rapport aux besoins |
Le niveau « Extra High » n’est pas utilisé pour ce facteur.
Le mot essentiel est donc besoin. Il ne s’agit pas de mesurer le nombre de pages produites, mais de déterminer si l’effort documentaire est proportionné à l’utilisation future de cette documentation.
Les coefficients COCOMO II
Les coefficients d’effort associés sont :
| Niveau | Coefficient |
| Très faible | 0,81 |
| Faible | 0,91 |
| Nominal | 1,00 |
| Élevé | 1,11 |
| Très élevé | 1,23 |
Ces coefficients produisent un résultat qui peut sembler paradoxal : moins documenter réduit l’effort de développement estimé par COCOMO II.
Mais il faut éviter une mauvaise interprétation. Le modèle ne dit pas qu’une documentation insuffisante est économiquement préférable sur l’ensemble de la vie du logiciel. Il indique qu’elle nécessite moins d’effort pendant le développement.
Le manuel COCOMO II précise au contraire que les économies réalisées avec une documentation faible ou très faible génèrent généralement des coûts supplémentaires pendant la maintenance.
Exemple : un projet de 1 000 jours-homme
Prenons un projet dont l’effort serait de 1 000 jours-homme au niveau nominal, toutes les autres caractéristiques restant identiques.
| Niveau | Coefficient | Effort | Écart / nominal |
| Très faible | 0,81 | 810 j.h | –190 j.h |
| Faible | 0,91 | 910 j.h | –90 j.h |
| Nominal | 1,00 | 1 000 j.h | Référence |
| Élevé | 1,11 | 1 110 j.h | +110 j.h |
| Très élevé | 1,23 | 1 230 j.h | +230 j.h |
Entre les deux situations extrêmes, l’écart atteint donc 420 jours-homme.
Rapporté aux 810 jours-homme du niveau très faible, cela représente environ 52 % d’effort supplémentaire.
L’ordre de grandeur est suffisamment important pour que le niveau de documentation constitue une véritable hypothèse de chiffrage.
Cas concret : un portail client
Imaginons une entreprise qui développe un portail destiné à ses clients.
La première version doit être mise en production rapidement. Pour respecter le calendrier, l’équipe réduit fortement la documentation : certaines règles de gestion restent uniquement connues des développeurs, plusieurs décisions d’architecture ne sont pas formalisées et les interfaces sont partiellement documentées.
À court terme, le projet gagne effectivement du temps.
Deux ans plus tard, une autre équipe reprend l’application pour réaliser une évolution importante.
Elle doit comprendre les règles existantes, retrouver les raisons de certains choix techniques, analyser les interfaces et interroger les personnes encore présentes.
L’économie réalisée pendant le développement initial est alors partiellement ou totalement consommée par le travail de compréhension.
À l’inverse, produire dès l’origine plusieurs centaines de pages qui ne seront jamais utilisées n’aurait pas davantage de sens.
Pourquoi un tel impact ?
La documentation consomme directement du temps.
Il faut :
- la produire ;
- la relire ;
- la valider ;
- la mettre en cohérence ;
- la versionner ;
- la maintenir lorsque le logiciel évolue.
Demander davantage de documentation augmente donc logiquement l’effort du projet.
Mais une documentation utile facilite ensuite la compréhension du logiciel, sa maintenance, son exploitation et son évolution.
Le véritable arbitrage est donc temporel : combien investir aujourd’hui pour éviter des coûts demain ?
La réponse dépend notamment de la durée de vie prévue de l’application, de sa criticité, du nombre d’équipes amenées à intervenir et de la fréquence prévisible des évolutions.
Les symptômes d’une documentation mal dimensionnée
Une documentation insuffisante se repère souvent lorsque :
- seules quelques personnes savent expliquer le fonctionnement du système ;
- les règles de gestion sont difficiles à retrouver ;
- les choix d’architecture ne sont pas tracés ;
- une nouvelle équipe met beaucoup de temps à devenir opérationnelle ;
- les documents existants sont anciens ou contradictoires.
Une documentation excessive présente d’autres symptômes :
- documents produits uniquement pour satisfaire un processus ;
- informations identiques reproduites dans plusieurs supports ;
- validations documentaires longues ;
- documents rarement consultés ;
- coût important pour maintenir la documentation à jour.
Dans les deux cas, le problème est le même : l’effort documentaire n’est plus aligné sur son utilité réelle.
Conséquences sur le chiffrage
Lors d’un chiffrage, demander simplement « faut-il produire de la documentation ? » est insuffisant.
Il faut comprendre les exigences concrètes.
Quelques questions sont particulièrement utiles :
- Quels livrables documentaires sont obligatoires ?
- Qui les utilisera ?
- Doivent-ils faire l’objet d’une validation formelle ?
- Quelle est la durée de vie prévue de l’application ?
- Plusieurs équipes ou prestataires devront-ils reprendre le logiciel ?
- Existe-t-il des contraintes réglementaires ou contractuelles ?
- La documentation doit-elle être maintenue pendant toute la durée du projet ?
Une erreur fréquente consiste à prendre un historique de projets relativement peu documentés et à l’utiliser pour chiffrer un projet soumis à des exigences documentaires beaucoup plus importantes.
L’estimation risque alors d’être mécaniquement sous-évaluée.
Comment améliorer ce facteur ?
L’objectif n’est pas de réduire systématiquement la documentation, mais de supprimer la documentation sans valeur tout en sécurisant celle qui sera réellement utile.
Trois leviers sont particulièrement efficaces.
1. Identifier les utilisateurs de chaque document
Un document sans utilisateur clairement identifié mérite d’être questionné.
2. Adapter la documentation à la durée de vie du système
Un prototype destiné à disparaître dans six mois ne nécessite pas le même investissement qu’un système industriel qui devra être maintenu pendant quinze ans.
3. Éviter les duplications
Une même information reproduite dans plusieurs documents augmente les coûts de production et surtout les risques d’incohérence lors des évolutions.
Quel impact des IA génératives ?
Les IA génératives modifient sensiblement l’économie de la documentation.
Elles peuvent faciliter la génération de synthèses, la transformation d’exigences en documentation structurée, la description d’interfaces ou encore la mise à jour de certains documents à partir des artefacts du projet.
Le coût de production documentaire peut donc diminuer.
Mais cela ne supprime pas le problème posé par DOCU.
Produire automatiquement dix documents inutiles reste moins pertinent que produire les deux documents réellement nécessaires.
De plus, une documentation générée automatiquement doit rester fiable, cohérente avec le système effectivement développé et suffisamment validée lorsque les enjeux l’exigent.
L’IA peut donc réduire le coût de production de la documentation, mais elle ne décide pas à elle seule de la documentation réellement utile au cycle de vie.
Les erreurs fréquentes
La première erreur consiste à considérer que plus de documentation signifie nécessairement plus de qualité.
La deuxième consiste à penser que les méthodes agiles ont supprimé le besoin de documentation.
La troisième est de considérer la documentation comme gratuite dans le chiffrage.
La quatrième consiste à mesurer la documentation en volume plutôt qu’en utilité.
Enfin, une organisation peut parfaitement disposer d’une documentation abondante mais inutilisable parce qu’elle est obsolète. La quantité ne garantit donc ni la qualité ni la valeur.
À retenir
- COCOMO II évalue l’adéquation de la documentation aux besoins du cycle de vie, pas simplement son volume.
2. Une documentation excessive augmente directement l’effort de développement.
3. Une documentation insuffisante réduit l’effort immédiat mais peut déplacer les coûts vers la maintenance.
4. Sur notre projet de référence, les coefficients font varier l’effort de 810 à 1 230 jours-homme.
5. L’objectif économique est de produire la documentation qui sera réellement utile.
Quelles décisions pour un DSI ?
Pour un DSI, DOCU invite à sortir d’une logique binaire opposant les organisations qui « documentent » à celles qui « ne documentent pas ».
La bonne décision consiste à définir le niveau documentaire en fonction du cycle de vie attendu de chaque catégorie d’application.
Une application critique, réglementée, maintenue pendant quinze ans et confiée successivement à plusieurs prestataires nécessite naturellement davantage de capitalisation qu’une application temporaire.
Cette exigence doit ensuite être intégrée explicitement au chiffrage des projets.
Enfin, l’arrivée des IA génératives constitue une opportunité pour réduire le coût de certaines activités documentaires. Mais elle doit aussi conduire à se poser une question plus fondamentale : si produire de la documentation devient très facile, comment éviter d’en produire trop ?
« La bonne documentation n’est ni maximale ni minimale : elle est utile. »
Le conseil Estimancy
Avant de chiffrer un projet, ne demandez pas uniquement la liste des documents à produire.
Identifiez qui utilisera chaque document, pour quelle activité et pendant combien de temps.
Vous distinguerez ainsi plus facilement la documentation nécessaire au cycle de vie du logiciel de celle produite uniquement par habitude ou par processus.
Les niveaux et coefficients repris dans l’article correspondent à la table 22 du manuel COCOMO II fourni. Le manuel indique également qu’une documentation faible ou manquante accroît les difficultés de compréhension du logiciel lors de sa réutilisation ou de son évolution.
