La documentation : le parent pauvre des projets

La documentation projet, un livrable a minima //

Le coût d’une mauvaise documentation est rarement mesuré, si ce n’est même identifié. Le plus souvent, la documentation initiale est un minimum, rédigée lors de la conception d’une application ou d’un SI. S’ajoute çà et là, celles de quelques projets d’évolutions majeures, mais celles-ci meurent le plus souvent, soigneusement rangées, dans une Gestion Electronique des Documents (GED). La documentation redeviendra un sujet d’attention lorsque l’on doit consolider les livrables à remettre au client en fin de projet.

 

Pourtant, les règles de l’art sont connues de tous. Le chef de projet est supposé fournir des documents (ou livrables) à chaque étape du projet :

• • Une Expression de Besoins ou un Cahier des charges au démarrage.
• • Une Spécification Fonctionnelle Générale (SFG), des Spécifications Fonctionnelles Détaillées (SFD) avec des cas d’utilisation pour les spécifications de la Maîtrise d’Ouvrage (MOA).
• • Une Spécification Technique Générale (STG), et éventuellement Détaillées (STD) par module développé avec des cahiers de tests qui conviennent.
• • Un cahier de recette est souvent renseigné lors de la phase de recette.
• • Parfois, une documentation d’exploitation est fournie un peu avant la Mise En Production.

La documentation, le carnet de santé du projet //

Les révisions apportées suite à des bugs corrigés lors de la recette et les évolutions techniques ou fonctionnelles ne font cependant pas toujours l’objet d’avenants contraignant. Cela poussent les équipes projet à traiter les besoins, se disant qu’ils enrichiront leurs documentations après la Mise en Production (MEP), pressées par les échéances contraignantes de la livraison du projet.

Or, le client et l’équipe projet conviennent le plus souvent lors du cadrage que ces documentations seront à fournir, mais on oublie souvent l’utilité réelle de ces informations et quels en sont les destinataires premiers :

• • Le service assurant la maintenance (TMA) d’une part, pour assurer le support, doit comprendre précisément le fonctionnement de l’application pour diagnostiquer plus efficacement le moindre dysfonctionnement.
• • L’équipe en charge de projets d’évolution d’autre part, doivent tenir compte du fonctionnement actualisé de l’application, impliquant toutes les évolutions et correctifs apportées au fil du temps.

La documentation comme étape nécessaire au transfert de compétences //

Or, un projet d’évolution important est toujours isolé, et enrichit rarement une documentation applicative. Dans celle-ci, on y trouve (au mieux) un fonctionnement actuel du logiciel, et surtout l’évolution que l’on souhaite apporter.

Cependant, le maître d’œuvre accompagné souvent une équipe externe, remet sa documentation au client, mais la TMA étant assurée par une autre équipe externalisée, cette documentation projet ne vient se substituer que trop rarement à la documentation applicative. Celle-ci vient se ranger proprement dans un fichier zip, constituant l’un des livrables contractuels à remettre au client. Le transfert de connaissance vers ces équipes est d’ailleurs souvent négligé.

 

C’est précisément à ce moment-là que cette documentation perd tout son intérêt : ces informations devraient naturellement se substituer, de manière morcelée dans une documentation applicative préexistante au projet d’évolution.
Les modifications des structures de tables devraient enrichir les modèles de données, les nouveaux batchs ou nouvelles modifications devraient être centralisés au même endroit, de même pour les web-services ou tout autres programmes modularisés… Le fonctionnement global de l’application s’en retrouve rarement remis en cause, et la dérive induite nous amène vers ce que l’on appelle communément une dette technique.

La documentation, un ROI à long terme

Je dresse certainement un tableau noir de cette gestion documentaire, auquel on pourra m’opposer de bonnes pratiques, des normes contraignantes, des processus de mises à jour, ou encore des exemples de GED actualisées, suivi et facilement accessibles. Mais alors je m’étonne de les trouver trop rarement sur les différents comptes sur lesquels je suis intervenu jusqu’ici. Où sont les parcours d’intégration ? Où sont les documentations explicatives ? Où sont les organisations de ces documentations ? On me répond le plus souvent « Dans le SharePoint » et me voilà perdu dans des centaines de répertoires dont les titres si peu évocateurs devaient paraitre évident à leurs rédacteurs, en leur temps.

Mon message ici, cherche surtout à sensibiliser le lecteur quant à la réelle utilité d’une documentation, destinée à garantir la pérennité du logiciel, à économiser la maintenance et à réduire les coûts d’évolution. Il est compliqué de motiver le budget d’une partie du projet pour l’avenir, cela nécessite d’avoir une vision à long terme, presque altruiste pour nos successeurs.

Un non-sens lorsque l’on pilote à vue et que l’on doit boucler un budget contraint. La qualité à un coût, et peu de gens sont prêts à y mettre le prix.