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 :

    typologie_documents6

  • 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
Cet article a été posté dans Méthode.

3 commentaires sur “La place de la documentation dans les projets agiles”

  • Merci pour ce post/fiche pratique à garder bien proche de soi :) La documentation est trop souvent perçue comme une tache rébarbative, inutile et souvent mal faite ET non relue! - Tu as fait telle doc ? - Oui - OK merci, tache suivante Alors que la documentation devrait toujours etre relue par une autre personne et modifiée si besoin sans que cela vexe la personne qui l'a faite initialement... De plus, on retrouve dans presque tous les projets de la documentation technique (archit. technique, process de livraison...) dont la dernière date de modification date du début du projet et dont la moitié du contenu est obsolète... L'estimation du temps pour réaliser une doc est souvent sur-estimé par manque de motivation :) Je finirai par dire que du coup, la documentation devrait toujours être réalisée par le client et non le prestataire car c'est lui qui est le plus interessé par la pérennité de ce contenu alors que le prestataire changera de projet bientôt... (c'est humain :) (parole de client :)
  • Ce qui est marrant (ou pas) c'est que 7 ans + tard le problème reste entier. Les documentations des projets sont faibles peu importe les méthodes. Les spécifications fonctionnelles ne sont pas remises à jour au fur et à mesure du projet, et le résultat livré ne reflète pas les spécifications fonctionnelles du début. En méthode Agile les users stories sont complètes mais difficiles à réarticuler entre elles de façon digeste pour les clients. En cycle en V, la documentation est relativement complète mais tout aussi indigeste et difficile de la remettre à jour. Balle au centre en gros.
  • Article toujours d'actualité plus de 10 ans après ! Je rajouterai dans les acteurs consommateurs de la documentation, les équipes qui sont chargées de faire de la conception traverse vs agilité à l'échelle.
    1. Laisser un commentaire

      Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *


      Ce formulaire est protégé par Google Recaptcha