La documentation dans les méthodes Agiles

Il y a encore beaucoup de questions sur comment gérons-nous correctement la documentation dans l’ensemble des méthodes agiles ? Et la réponse pour être honnête est loin d’être simple.

Partons du plus connu : le Scrum d’aujourd’hui

La différenciation entre les méthodes agiles n’est pas anodine car si elles tentent toutes de respecter l’une des 4 valeurs du Manifeste Agile, l’interprétation de cette phrase peut facilement différer.

Valeur du Manifeste Agile : « Des logiciels opérationnels plus qu’une documentation exhaustive »

Si on partait de la user-story ?

Dans la généralité des projets Scrum, les équipes commencent la documentation par l’implémentation de user-stories (pratique venant de l’Extrême Programming).

Que mettre dans nos user-stories ? Certaines équipes arrivent à développer des applications avec des user-stories qui rentrent sur une petite feuille. Cependant sur un très grand nombre de projet, je crains que cette pratique  amène un manque de précision qui peut coûter cher à l’avenir : comment s’assurer des règles de gestion ? Comment les retrouver plus tard ?

Pour s’assurer d’une compréhension parfaite de la user-story, il semble indispensable de l’alimenter de règles de gestion, de wireframe, de scénarios de tests voire d’autres éléments complémentaires car il n’existe pas un format parfait.

Voici un exemple de format que j’avais présenté dans le passé mais qui n’est pas le seul existant (le meilleur format est celui qui convient le mieux à l’équipe) : Un format de user-story très efficace : le story A4

La user-story vraiment suffisante ?

Petite phrase que j’ai entendu dans le passé : « l’agile dit pas de docs exhaustives donc on fait pas de docs… ». L’interprétation est simpliste et bien loin de l’idée dégagée par le manifeste agile ; le soucis c’est qu’il faut lire le début de la phrase« Des logiciels opérationnels plus qu » pour comprendre l’ensemble de la philosophie sur le sujet.

« Plus que » veut bien dire qu’on exclue pas la documentation (même exhaustive si on va à l’exagération de l’interprétation) mais qu’on privilégie le logiciel. En fait la documentation va pourquoi pas partir du logiciel et non l’inverse comme on le voit dans les méthodes de gestion de projet tels que le Cycle V ou autres waterfall. Certaines méthodes agiles autres que le Scrum actualisé font cependant des docs dites essentielles avant le développement (mais pas de documentation exhaustive)

Dans certains contextes, la user-story n’est pas suffisante car son historisation peut rapidement se transformer en vrai casse-tête. De plus, on n’y met par exemple jamais plus qu’un simple découpage technique sur les aspects techniques de l’application.

En fait, en agile on peut créer des docs complètes voire il ne faut surtout pas s’en priver, mais souvent après le développement. Faire de la documentation après le développement amène la documentation à être beaucoup plus proche de ce qui a été livré.

Vous pouvez avoir besoin d’avoir une documentation technique du socle technique de l’application, d’une documentation utilisateur et d’une documentation fonctionnelle. Ne vous en privez pas, ce serait une erreur.

Seulement la documentation nécessaire

La documentation  dans le monde agile se réalise de façon incrémentale ; un projet s’améliore au fur et à mesure des feedbacks clients donc on fait la documentation au fur et à mesure.

Si cette façon de faire change le travail des équipes, cela n’enlève pas le besoin de documentation indispensable pour la pérennité du produit. Contrairement aux méthodes de gestion de projet comme le cycle en V, il est nécessaire pour un projet de voir sa documentation se construire au fur et à mesure car sinon une partie de celle-ci sera une perte de temps inutile.

Faire des documentations KISS

C’est un conseil que je vous donne, n’hésitez pas à simplifier au maximum vos documentations afin de partir dans cette philosophie KISS (Keep it simple, Stupid) qui peut également  s’appliquer à la documentation.

Article : Le principe KISS pour les développeurs

Simplifier une documentation permet de pouvoir la maintenir plus facilement, d’offrir plus de chance au produit d’évoluer car les futurs membres de l’équipe la comprendront mieux…

Pour les user-stories, le rassemblement des user-stories par Epic (et par thème au niveau supérieur) peut énormément aider à simplifier au maximum la documentation fonctionnelle ; cela est même suffisant pour être représentatif de la documentation fonctionnelle du produit.

Cependant cela implique un très bon découpage des user-stories et l’utilisation d’Epics et de Thèmes (que le story mapping aide vraiment à gérer).

Votre documentation fonctionnelle pourrait être un Jira avec le plugin Story-mapping tout simplement. Mais sans ça, chercher des règles de gestion sur des fonctionnalités dans le futur sera un vrai casse-tête.

Pour vous aider à bien gérer ce découpage je ne peux que vous conseiller de passer par des techniques de framing telles que celles que je vous propose avec la création d’un story mapping pour lancer un projet voire pour ajouter des fonctionnalités :

Articles :
Bien comprendre la création d’un story-mapping
Lancer une fonctionnalité en faisant un Starter Agile

Et pour la partie technique ?

Pour ceux qui font du storyotype pour embarquer d’autres demandes que des user-stories (souvent indispensable bien que trop souvent oublié) avec des demandes du type : tâche technique, spike, bugs… on ne pourra que très difficilement les utiliser en live pour les documenter.

Article : Faire des user-story de différents storyotypes

Sachant que l’agilité d’aujourd’hui centre au maximum ses développements sur la valeur business (soit pour les utilisateurs clés de façon fonctionnelle), la partie technique est totalement déstructurée dans ces documentations.

Je conseille fortement d’utiliser un wiki ou équivalent pour faire des docs sur la partie technique en restant bien évidement KISS.

Attention, cela n’empêche pas de bien documenter le code afin que les futurs développeurs puissent sans soucis comprendre en un coup d’oeil chaque partie du code. C’est surtout en cas de bugs complexes qu’on remercie ceux qui ont bien fait ce travail.

Que disent certaines méthodes agiles ?

Cette partie est plus pour votre culture agile mais la méthode agile que nous allons voir ici n’est pas utilisée en France. Cependant, on peut y trouver de très bonnes choses.

Rappelons que le Scrum ne parle pas de phase d’initialisation contrairement à d’autres méthodes agiles. Par exemple, le DSDM préconise de faire un Rapport de Faisabilité ainsi qu’un Plan Global de Développement lors de l’étude de faisabilité qui se définissent sous forme de documents.

On ne parle pas de documentation exhaustive mais de documentation bien axée sur des sujets précis.

Dans cette méthode on parle également de la création du document appelé Définition du Domaine Industriel et du document appelé Définition de l’Architecture Système lors de l’étude business du DSDM

Article : Qu’est-ce que le DSDM ?

Comme vous pouvez le constater les autres méthodes agiles sont bien plus documentaires que le Scrum ou du moins de l’interprétation qu’on a voulu en faire.

NON, les méthodes agiles n’interdisent pas les documentations mais elles privilégient qu’on mette l’effort sur le logiciel opérationnel et non sur les documentations.

Conclusion

J’espère que cet article vous aura permis d’y voir plus clair pour faire de la documentation dans les méthodes agiles. Il existe probablement d’autres recommandations mais j’espère que celle que je vous apportent ici vous aiderons dans vos projets.