Nombreuses sont les organisations publiques et privées qui adoptent la méthode Agile pour la gestion de leurs projets de transformation numérique. L’un de ses aspects suscite notamment de nombreux questionnements : la documentation des projets de « façon Agile ». Dans cet article, nous allons nous pencher sur ce sujet important et malheureusement bien souvent négligé dans le cadre du développement Agile.

Rédigé par Charles-Olivier Mercier, Coach Agile chez Cofomo

Que faut-il documenter?

Tout d’abord, il est important que l’équipe détermine dans quel but elle produit de la documentation, quelle est l’utilité de cette documentation et qui sont les utilisateurs qui en tireront des bénéfices.

Si l’on se concentre sur la phase de réalisation d’un projet Agile, la documentation des récits utilisateurs est généralement suffisante pour qu’une équipe comprenne bien les besoins du projet et qu’elle parvienne à développer une fonctionnalité. La documentation des histoires peut alors revêtir la forme d’exigences fonctionnelles ou de critères d’acceptation, mais une équipe peut également vouloir documenter des spécifications techniques comme lorsqu’elle réalise des Behaviour-Driven Developments (BDDs).

Une fois les histoires réalisées, la documentation permanente doit être conçue pour permettre à toute nouvelle personne de l’équipe de comprendre les choix qui ont été pris et dans quel contexte, et pourquoi le produit fonctionne ainsi. Cette documentation plus pérenne devrait être minimale afin d’être digeste, tout en permettant aux gens de comprendre rapidement le fonctionnement d’un produit. Simplicité, efficacité.

Quel format ?

Il n’existe pas de format prescrit sur la manière dont la documentation devrait être réalisée dans le cadre de projets Agiles. Cette liberté peut à la fois être bien accueillie, mais elle peut aussi amener son lot de questionnements.

Par exemple, si des équipes ou des organisations sont habituées de produire un certain type de livrables (format, construction, outils, etc.) revoir la façon dont la documentation est produite demande une réorganisation du travail et représente un certain effort. Celui-ci consiste à remettre en question la documentation en cours d’écriture, pour tenter de garder uniquement ce qui est essentiel pour l’équipe projet. Le temps investi à réviser la méthode de documentation ne sera pas vain puisqu’il permettra des économies de temps, en plus d’améliorer l’utilisation de la documentation et la compréhension des personnes qui l’utilisent.

Le nouveau format utilisé pourrait alors être inspiré des façons de faire existantes, en prenant soin de les alléger et d’éliminer les parties qui ne sont plus utiles à leurs utilisateurs. L’objectif principal est de produire une documentation qui permette de comprendre l’essentiel et que l’on soit capable de s’y retrouver facilement.

Par exemple, il est possible que des gabarits de livrables soient utilisés dans votre entreprise, sans que personne n’ait remis en question l’intérêt de documenter certaines sections. Des sections contenant des informations peu pertinentes sont alors documentées sans que personnes n’en ait besoin. Ce travail a pour effet de diluer l’information pertinente, en plus de demander des efforts non nécessaires aux personnes qui l’effectuent. En ajustant ce type de livrable, on s’assure ainsi que la documentation soit aussi facile à produire qu’à utiliser. Cela permet également d’éviter que ce qui devrait être un actif pour l’organisation devienne trop difficile à maintenir ou qu’il comporte des informations redondantes.

À quel moment?

Nous avons déjà parlé de l’importance de documenter les histoires au cours du processus de développement. En documentant les histoires au cours du processus de développement, les membres d’une équipe peuvent mieux comprendre les besoins, mieux communiquer et ainsi mieux collaborer.
Qu’en est-il de la documentation pérenne, celle qui va être conservée et servir de cadre de référence pour la poursuite du projet? Dans le cadre d’un projet Agile, les décisions peuvent changer rapidement et il est conseillé de garder une trace de l’historique des décisions tant que celles-ci ne sont pas complètement arrêtées. Souvent, cette phase de maturité des fonctionnalités (ou d’un projet) n’est atteinte que tard dans le processus de développement, par exemple à la fin d’une itération ou lorsque qu’une fonctionnalité a été livrée et est déjà utilisée en production. C’est donc à ce moment que les équipes devraient concentrer leurs efforts, pour s’assurer de documenter les décisions prises concernant les fonctionnalités qui ne changeront plus. Cette situation est bien imagée par Scott Ambler dans son cadre le « Disciplined Agile »:

Si cet exemple fonctionne pour plusieurs équipes, il est difficilement applicable aux équipes utilisant l’intégration ou la livraison continue. Dans ce cadre-là, ces équipes ont généralement réussi à optimiser l’ensemble de leur processus de développement et ont besoin de produire de la documentation rapidement et constamment. Ils peuvent alors avoir recours à des outils comme SandCastle, conçus pour générer dynamiquement de la documentation à même le code.

Comment aider votre équipe à atteindre ses objectifs?

De nos jours, nous avons accès à une pléthore d’outils de collaboration en temps réel (ex. : Confluence, Azure DevOps Wiki, etc.), et même capables de générer de la documentation de façon dynamique. Tous ces outils ont pour mission principale de nous faciliter la vie et il ne nous reste alors qu’à déterminer la manière dont nous voulons les utiliser.

Une fois la structure de la documentation définie, il faut s’intéresser à la manière dont les équipes peuvent s’organiser pour être efficaces.

 Une bonne pratique possible est d’inclure les efforts de documentation dans le processus de réalisation Agile tel que dans la « notion de terminé ». Cette façon de travailler de manière décentralisée permet de s’assurer que tous comprennent les exigences requises en termes de documentation, et la qualité de celle-ci devient un objectif commun.

Dans tous les cas, si une équipe souhaite apporter des changements à ses méthodes de travail et ses processus, elle aura besoin de s’assurer que tous comprennent l’importance que ceux-ci ont dans la qualité de la documentation produite et dans la « notion de terminé ». La force des équipes Agiles se voulant multidisciplinaires et auto-organisées réside dans leur capacité à décentraliser certaines responsabilités comme la documentation, plutôt qu’à l’impartir à des rôles spécifiques (ex. : analystes ou architectes). La documentation devient alors un enjeu commun, et si des ajustements sont nécessaires, l’équipe devra trouver la façon de fonctionner qui conviendra le mieux.

Adopter ce type de façon de faire plus Agile et plus légère aura des impacts qui nécessiteront un certain temps d’adaptation. La seule manière d’arriver à trouver cet équilibre dans le niveau de documentation sera ultimement en l’essayant, en apprenant de nos erreurs et en s’adaptant en continu!

Conclusion

Pour finir, les approches Agiles ne sont pas prescriptives et suggèrent plutôt de documenter minimalement selon les besoins d’une équipe ou d’une organisation.

 Les approches comme Scrum se veulent des cadres de développement plutôt que des méthodologies dogmatiques. Elles laissent place à la créativité des équipes pour que celles-ci trouvent les solutions qui répondent le mieux à leurs besoins. Ces solutions peuvent passer par l’allègement d’une structure de documentation existante, comme elles peuvent prendre une forme totalement différente.

Il est donc important de retenir qu’il appartient aux équipes de définir quels sont leurs besoins et comment est-ce que la documentation devrait y répondre.

Enfin, gardons en tête que c’est le développement de logiciels devrait être favorisé plutôt que de mettre l’emphase sur la documentation. Comme le mentionne le manifeste Agile, la documentation n’amène pas de valeur sans le produit qu’elle sert à supporter.