Lorsque le Manifeste agile a posé le principe selon lequel « Un logiciel fonctionnel est plus important qu’une documentation exhaustive » en 2001, les équipes de développement se sont réjouies à l’idée d’adopter une nouvelle méthode de travail.

Avoir une importante documentation était la norme, mais freinait l'efficacité de l'entreprise. La création de cette documentation prenait beaucoup de temps, laissait peu de place aux modifications et nécessitait une maintenance permanente. Cette courte formule du Manifeste agile reconnaissait ces difficultés et de nombreuses équipes en ont profité pour dire adieu à la documentation une fois pour toutes.

Mais les équipes qui ont cessé de rédiger de la documentation ont été confrontées à d’autres problèmes : elles ont rencontré des difficultés pour partager leurs connaissances, se mettre d’accord sur les décisions et avancées, former les nouveaux membres de l’équipe ou résoudre les incidents. Ces défis se sont intensifiés au cours des dernières années avec l’essor du télétravail.

Il est clair qu’un développement lourd et axé sur la documentation n’est ni efficace ni productif, mais l’élimination pure et simple de cette dernière ne l’est pas non plus. D’où la question suivante : quel est le rôle de la documentation dans une approche agile ?

Pour le savoir, nous nous sommes entretenus avec James Grenning, l’un des co-auteurs du Manifeste agile et le fondateur de Wingman Software. Dans cette interview, M. Grenning explique l’intention qui se cache derrière cette formule souvent mal interprétée du Manifeste agile et aborde la manière dont les équipes agiles modernes peuvent trouver le juste équilibre en matière de documentation pour travailler efficacement.

Revenons à la création du Manifeste agile : qu’est-ce qui a motivé cette initiative ?

James Grenning : À l’époque, je travaillais avec Bob Martin et il m’a demandé si je voulais participer au Lightweight Methods Summit à la station de ski de Snowbird, dans l’Utah. Les méthodes légères (Lightweight Methods en anglais), désignaient des approches telles que l’Extreme Programming, le Feature-Driven Development et Scrum, qui comportaient toutes un minimum de cérémonies et d’artefacts par rapport aux approches plus lourdes adoptées dans les années 80 et 90.

J’étais partisan de l’approche Extreme Programming (XP), mais des experts de toutes les Lightweight Methods étaient présents au séminaire. Bien que nous venions d’horizons différents, nous partagions le désir d’améliorer les méthodes de développement logiciel. Sur le ton de la plaisanterie, nous tenions à éviter d’être identifiés comme les « poids plumes ». Un autre objectif était donc de trouver un nouveau nom, qui est aujourd’hui celui d’agile.

Il y a eu beaucoup d’échanges et de divergences d’opinions, l’accent étant mis sur les points sur lesquels nous pouvions nous entendre. Je suis ingénieur et je m’attendais à parler beaucoup de processus techniques, mais les ressources humaines et le travail d’équipe sont apparus comme des thèmes majeurs. Nous avons formulé nos idées sous forme d’énoncés comparant des valeurs et en privilégiant l’une plutôt que l’autre, tout en prenant soin de préciser que les éléments les moins favorables conservent néanmoins leur importance. C’est ainsi que nous avons abouti aux quatre principes que vous connaissez aujourd’hui.

Je ne m’attendais pas vraiment à ce que les gens s’intéressent au Manifeste agile lorsque Ward Cunningham l’a mis en ligne sur un site Web, mais beaucoup de programmeurs s’y sont intéressés. Cela m’a surpris, mais cela montre aussi que beaucoup de personnes sont conscientes des difficultés du développement logiciel et cherchent une meilleure façon de travailler.

Penchons-nous sur l’une des affirmations du Manifeste agile. Quelle était l’intention première derrière « Un logiciel fonctionnel est plus important qu’une documentation exhaustive » ?

JG : L’état d’esprit à l’époque était de « documenter d’abord, construire ensuite ». Mais la documentation est coûteuse. Ce n’est pas seulement un avantage, c’est un coût.

L’un des objectifs de la documentation classique était de mettre les demandes du client par écrit et de les faire approuver d’emblée par l’équipe de développement, afin de laisser cette dernière travailler librement. Le problème est que, lorsque les clients ne soumettent des demandes qu’une fois par an, ils vont réclamer toutes les fonctionnalités auxquelles ils peuvent penser, mais ils vont changer d’avis avant que le logiciel ne soit livré.

Kent Beck, Ward Cummingham, Ron Jefferies et d’autres partisans de l’XP avaient compris que cette manière de créer de la documentation était non seulement chronophage, mais qu’elle ne permettait pas à l’équipe d’intégrer les enseignements ou de réagir aux changements.

La formule « Un logiciel fonctionnel est plus important qu’une documentation exhaustive » représentait un changement fondamental dans l’état d’esprit entourant la documentation. Elle suggérait qu’au lieu de donner la priorité à une documentation complète dès le départ, nous pouvions créer progressivement une documentation de qualité à mesure que nous construisions le logiciel.

Il semble qu’aujourd’hui, il existe une stigmatisation autour de la documentation dans les contextes agiles. Pouvez-vous nous dire ce que vous pensez de son rôle ?

JG : Les énoncés du Manifeste agile se présentent sous la forme de « une chose plutôt qu’une autre ». Mais malheureusement, ils sont souvent mal interprétés comme « une chose et pas l’autre ». Nous voyons cela fréquemment avec la documentation.

Notre intention n’était pas d’insinuer que les équipes devaient faire l’impasse sur la documentation. Il est impossible de recommander une approche unique en la matière. Le Manifeste agile ne dit rien sur la façon d’aborder la documentation parce que nous ne saurions pas quoi conseiller : les besoins de chaque équipe sont différents. Mais le fait de ne pas fournir de directives spécifiques quant à la manière de créer une documentation ne signifie pas que vous n’en avez pas besoin.

La documentation peut être incroyablement utile pour créer une compréhension partagée entre les équipes et les parties prenantes. Par exemple, documenter la conception est indispensable pour la maintenance système, les réviseurs externes et les développeurs en télétravail. Il s’agit de comprendre que les besoins en documentation varient en fonction de facteurs tels que la taille de l’équipe, la répartition géographique, les réglementations ou le secteur d’activité.

Je recommande aux équipes d’utiliser le Manifeste agile comme point de départ, en déterminant les besoins uniques auxquels elles doivent répondre. Par exemple, une petite équipe partageant les mêmes locaux aura la possibilité de partager des informations techniques en personne ou à l’aide d’un tableau blanc, mais une grande équipe dispersée dans le monde entier devra trouver d’autres moyens de communiquer ces données.

Sachant qu’il n’existe pas de recette magique pour la documentation, quels conseils donneriez-vous aujourd’hui aux équipes agiles ?

JG : Tout d’abord, rappelez-vous que chaque document que vous créez doit avoir une utilité. Avant de créer une quelconque documentation agile, déterminez pour qui vous la créez et à quoi elle servira. Cela permet d’éviter le gaspillage et de gagner du temps en impliquant les bonnes personnes dans la création du document.

Lorsque vous décidez de créer un document, gardez ces conseils à l’esprit :

Utiliser des visuels pour fournir une vue d’ensemble cohérente

Les visuels sont excellents pour commencer à explorer des idées et mettre les gens sur la même longueur d’onde. Commencez par une vue d’ensemble de votre objectif. Vous pouvez considérer cela comme une carte. Lorsque vous créez un document de A à Z, commencez par décrire la situation, indiquez les règles à suivre et aidez votre équipe à se familiariser avec le système.

L’important est de savoir quand s’arrêter. Utilisez ces visuels pour explorer les interactions entre les systèmes et harmoniser vos effectifs, mais n’en faites pas trop. Il peut exister des dizaines de scénarios connexes - documentez-en quelques-uns pour illustrer le modèle et coordonner les parties prenantes.

Créer de la documentation de manière itérative

Commencez par une vision du produit. Elle est probablement vague et floue - documentez-la de la manière la plus simple possible. Il peut s’agir d’une liste de points ou de croquis sur un tableau blanc réel ou virtuel. Au fur et à mesure que le projet avance, cette vision se précise. Vous en découvrez davantage sur le problème à résoudre et sur votre solution potentielle.

Cette documentation est destinée à fournir des informations générales, alors tâchez de vous y tenir. Vous pourrez ensuite ajouter plus de détails dans le code lui-même. Par exemple, un diagramme UML indiquera les opérations représentatives, mais ne précisera pas la signature détaillée des fonctions. Votre carte du système vous aide à accéder aux détails plutôt que d’encombrer votre vision avec trop de précisions.

Vous pouvez également adopter une approche itérative avec du code auto-documenté : un code dont la structure et la syntaxe expliquent clairement le fonctionnement sans commentaires ni documentation supplémentaire. Par exemple, j’ai remarqué sur mon propre site Web des cas où le code que j’avais écrit était difficile à comprendre. Il semblait parfaitement clair lorsque je l’ai créé, mais beaucoup moins deux semaines plus tard. J’étais persuadé que quelqu’un s’était infiltré et avait saccagé mon code ! Je l’ai donc amélioré en modifiant les noms et la structure. Cela le rend beaucoup plus lisible et explicite lorsque j’y reviens.

Transformer le travail en cours en documentation.

Avant de créer un document, posez-vous la question suivante : existe-t-il un moyen de le rédiger de manière plus cohérente avec mon travail actuel ?

Une documentation exécutable permet de recueillir des informations détaillées sans générer d’efforts supplémentaires. Je vous donne l’exemple d’une entreprise pour laquelle j’ai travaillé il y a longtemps. Une étape du processus stipulait : documentez comment procéder à un test unitaire de votre code. Il s’agissait d’un processus manuel qui est devenu obsolète avec le temps.

Au lieu d’un processus manuel documenté, essayez les tests unitaires automatisés ! Cela signifie qu’au lieu d’écrire un document sur la façon dont le code se comporte, vous écrivez des tests qui confirment que le code se comporte de manière conforme. Lorsque celui-ci cesse de respecter son cahier des charges, le test échoue. Grâce à ce type de développement, les tests et le code restent naturellement synchronisés, sans compter que la répétition des tests est pratiquement gratuite.

Les tests deviennent la documentation. Ils vous indiquent en termes clairs comment le code est censé fonctionner, alors que ces informations, si elles étaient écrites dans une langue courante comme le français, seraient ambiguës et sujettes à interprétation. Un document peut devenir obsolète, mais les tests renvoient toujours des informations actualisées, sans créer de travail supplémentaire. Le document le plus économique est celui que l’on n’a pas besoin de rédiger.