la-documentation-projet-quel-enjeu-pour-l-entreprise

Le blog d'upnote

La documentation projet, quel enjeu pour l’entreprise ?

Le 04-11-2019

A l’heure de la montée en puissance des méthodes agiles dans nos organisations, j’observe une baisse drastique de la documentation produite sur les projets informatiques (conception fonctionnelle, conception technique, document d’architecture, …). En tant qu’ancien responsable assurance qualité cette baisse m’interpelle. Qu’en sera-t-il de la maintenabilité et du transfert de compétences de ces applications dans les années à venir ? N’est-ce pas là un risque inconsidéré que prend l’entreprise ?

J’ai longtemps pensé que cet état de fait venait du rééquilibrage de pouvoir qu’apportent les méthodes agiles entre les différentes parties prenantes. La documentation n’étant pas le sujet préféré des développeurs, celle-ci en pâtissait.

Et pourtant, il y a quelques temps de cela une ESN m’invitait à parler de la documentation en préambule d’un DOJO, sorte d’after work ou les développeurs se retrouvent pour coder.

Les réactions observées à l’énonciation du thème du préambule m’indiquèrent clairement que les 20 minutes de mon intervention allaient être rock’n roll.

Au terme de mon exposé il s’est pourtant produit quelque chose d’inhabituel, forçant les organisateurs à procéder à un vote pour ou contre la poursuite des échanges sur le thème, au détriment de la partie codage. La quasi-unanimité des personnes présentes ce soir-là a souhaité poursuivre sur le thème et nos échanges ont duré une bonne heure.

Il serait difficile de retranscrire ici toute la richesse qui en est ressortie, mais voici un résumé des principales difficultés remontées par mes interlocuteurs :

  • « On ne sait pas ce qui doit être mis mettre dans une documentation, et jusqu’à quel niveau de détail s’arrêter »,
  • « On a souvent peut de retour sur la documentation qu’on produit »,
  • « On ne sait pas à quoi sert notre documentation. » « On a souvent l’impression que ça ne sert à rien ».

J’en conclu donc que contrairement aux idées reçues, ce n’est pas le manque d’appétence des développeurs pour la documentation qui explique à lui seul ce constat. Les freins sont très probablement ailleurs.

Il est vrai qu’une documentation mal faite ne sert à rien. Pire, elle peut desservir le projet. Alors à quoi bon y passer du temps ? Eh bien c’est très certainement là qu’est l’erreur. Une bonne documentation est impérative à la pérennité du projet. La question devrait plutôt être « Quels moyen je me donne pour arriver à une documentation de qualité ? ».

Les réponses vous les connaissez pourtant puisque vous réalisez des projets. Il suffit de transposez les réponses à la question « Quels moyen je me donne pour arriver à un projet de qualité ? » en les appliquant à la documentation. Voici quelques pistes qui pourront étayer votre réflexion :

Tout d’abord, il est bon de fixer un objectif, si possible SMART (Spécifique, Mesurable, Acceptable, Réaliste, Temporellement défini). En d’autres termes, prendre le temps de définir de manière explicite les attentes concernant la documentation projet. Elles doivent correspondre au niveau de la personne en charge de sa réalisation ainsi qu’aux besoins du projets (ni trop, ni trop peu - le niveau de détail attendu peut varier fortement d’un projet à l’autre). Le budget temps alloué doit être réservé et communiqué.

Une fois l’objectif défini, pensez aux ressources. Du temps, nous venons de le voir, mais aussi et surtout aux personnes qualifiées et/ou à faire monter en puissance. L’idéal est de mixer les deux pour que le niveau moyen de l’équipe soit en augmentation permanente, et qu’en cas de départ le savoir-faire ne se perde pas. Une aide externe est parfois la bienvenue lorsque l’équipe n’as pas (plus) assez d’expérience. Un peu de sang neuf apporte souvent un bon coup de fouet.

Après la réalisation vient une phase trop souvent oubliée : les tests. Ils sont pourtant de rigueur ! La documentation projet est un livrable comme les autres (même lorsqu’elle est interne au projet). A ce titre, elle doit faire l’objet d’une recette (relecture par des pairs, relecture par des utilisateurs de la documentation pour lever les ambiguïtés). Il s’agît là d’une vraie démarche à mettre en place avec un processus de relecture défini (nombre et qualité des relecteurs, objectifs des relectures, relecture en double aveugle, prise en compte des retours, …) et des critères de validation clairs et objectifs des fiches de relectures et des documents relus.

La solution de diffusion de la documentation a-t-elle suffisamment requis votre attention ? Comment s’assurer que chaque destinataire soit bien informé des nouvelles versions et qu’il travaille avec la bonne version des documents. Combien coûte au projet une personne qui travaille sur une mauvaise version de document ? Quand cela s’est-il produit pour la dernière fois ?

La collecte et la diffusions des retours sont également importants. C’est grâce aux retours que votre documentation sera toujours à jour et que les rédacteurs progresseront le plus. Si les retours immédiats (relecture interne avant diffusion) sont souvent bien gérés, qu’en est-t-ils des retours à plus long terme, ceux réalisés par les utilisateurs de la documentation ? Comment sont-ils collectés, diffusés et traités ? Sont-ils tous collectés ? Sont-ils tous traités ?

J’aime enfin à rappeler la force de l’amélioration continue. Disposer d’un comité qui, à intervalle régulier, regarde avec un peu plus de hauteur la qualité de la documentation produite, son adéquation par rapport aux besoins des projets et la typologie des retours les plus fréquents est toujours une bonne idée. C’est un levier formidable qui vous permettra d’ajuster vos attentes, vos processus et les moyens requis.

Mettre en place une culture d’entreprise relative à la documentation projet est un investissement sur le long terme. Il faut gardez à l’esprit que l’amélioration de la qualité des documents s’étalera très probablement sur plusieurs projets. Les pièges les plus fréquents sont de vouloir aller trop vite en se donnant des objectifs démesurés au regard de la maturité des équipes en place. Il est souvent préférable de n’avoir que peu de documents et que ceux-ci soient vraiment utiles plutôt que d’avoir pléthore d’informations incohérentes que personne ne lira.

Si les premières réflexions doivent concerner les objectifs et les processus à mettre en place, consacrez également du temps au choix des outils. Cette étape est en effet souvent négligée en se précipitant sur les outils les plus simples ou les plus connus, mais pas toujours suffisant pour répondre à l'ensemble des besoins que nous avons évoqués. Et pourtant, bien choisis, les outils vous seront d’une grande aide dans l’acceptation, l’efficacité et la pérennité de vos processus.