La place de la documentation dans les projets agiles

Les équipes agiles mettent l’accent sur la livraison de user stories. Dans le Manifesto for Agile Software Development, on retrouve cette notion de priorité au  développement du logiciel : Working software over comprehensive documentation. Cette rupture par rapport au mode de pensée dans les méthodes classiques est souvent perçue par les équipes agiles jeunes et peu expérimentées comme une chasse à la documentation, et une dévalorisation totale de celle-ci.

Cet article est basé sur un retour d’expérience d’un projet :

• réalisé en agile depuis deux ans
• mis en production depuis plusieurs mois
• composé de 4 personnes avec un roulement d’une personne tous les 8 à 12 mois

Il a pour but de présenter le rapport des équipes agiles à la documentation projet en général et de fournir des pistes pour élaborer une documentation pertinente.

Le rapport des équipes agiles à la documentation projet

La distance avec la documentation dépend des acteurs et des cycles de vie du logiciel.

• Au sein de la MOE, et entre la MOE et la MOA Les méthodes agiles favorisent la communication au sein de l’équipe de développement. Les pratiques de binômage ou « pair-programming », qui sont courantes dans les projets agiles, par exemple, favorisent la prise en main du code par tous les acteurs du projet. Le besoin de documenter des processus liés au développement comme l’installation du poste de développeur ou le processus méthodologique de traitement d’une fonctionnalité n’est pas ou peu ressenti. Le capital de connaissance de l’équipe se transmet par voie orale.

Les méthodes agiles fluidifient également la communication entre les acteurs MOA et MOE. Il est même préconisé que les deux parties soient géographiquement proches. La MOE a donc un backlog avec des user stories fonctionnelles claires, et est en plus proche de la MOA sans qu'un besoin de documents particuliers se fasse sentir.

En revanche, dès que le cycle de vie du logiciel change, et qu’il y a moins de transmission par voie orale, par exemple lors du passage du projet en TMA (Tierce Maintenance Applicative), le besoin en documentation est plus fort, et trouve donc tout son sens.- Au sein de la MOA La MOA doit être en mesure de justifier les choix fonctionnels pris. A ce titre, il est courant que la MOA fournissent des documents expliquant le contexte fonctionnel, les choix pris et leurs justifications, et ce, dès les premières itérations du développement logiciel.- Utilisateurs finaux et exploitation Les méthodes agiles impliquent une livraison, une recette et une démonstration aux utilisateurs finaux à chaque fin d’itération. Les besoins de documentations d’exploitation ou pour les utilisateurs finaux apparaissent pendant la phase de développement et s’affinent au-fur-et-à mesure des itérations.

Construire une documentation pertinente

• Identifier les consommateurs de la documentation

  Identifier les consommateurs de la documentation permet de comprendre l’objectif de cette dernière, de s’assurer de ne faire que le nécessaire et de s’aligner sur cet objectif. Voici la classification qui a été mise en place :

  • Documentation destinée à l’équipe de TMA (documentation pour l’équipe de développement, après la phase de développement du logiciel)
  • Documentation destinée aux équipes de production et d’exploitation
  • Documentation destinée aux utilisateurs finaux De cette classification découlent des tâches plus précises. Le tableau suivant résume par exemple les typologies de documents qui ont pour but de faciliter la prise en main du projet par les équipes TMA :

- Inclure la documentation aux itérations, au plus tôt Le product owner a une responsabilité importante sur ce volet. Il doit avoir une vision transverse du projet, aussi bien sur le périmètre fonctionnel que sur les besoins en documentation. Il doit avoir la capacité d’anticiper sur les différents besoins en documentations : utilisateur final, exploitation, TMA, ... Ceci veut dire qu’il faut inclure dans le backlog des itérations aussi bien des user story fonctionnelles, que des tâches de documentation.

Ces tâches documentaires, doivent être priorisées par valeur apportée, estimées, livrées et « recettées » tout comme n’importe quelle autre user story fonctionnelle. La fraîcheur de la description fonctionnelle des règles de gestion est primordiale. Il est nécessaire d’ajouter dans le DoD (Definition Of Done) d’une user story, la documentation des nouvelles règles de gestion ajoutées ou la mise à jour de celles déjà existantes.

Conclusion

• Documenter, c’est capitaliser une partie de la connaissance fonctionnelle et technique de l’équipe projet, pour la transmettre aux équipes de TMA, de production ou les utilisateurs finaux ;
• Construire une documentation pertinente c’est ;
  • Définir les consommateurs finaux de la documentation, et décliner leurs besoins en tâches documentaires
  • Définir un processus de documentation, s’assurer de l’alignement des acteurs projet, et l’intégrer aux itérations