Q&R Avec Cyrille Martraire Pour Son Livre Living Documentation

Dans le livre Living Documentation, Cyrille Martraire explique que nous devrions repenser la façon dont nous travaillons avec la documentation quand nous développons des systèmes logiciels : nous devrions adopter une documentation qui évolue à la même vitesse que le code. La documentation traditionnelle est pour lui un sujet ennuyeux, souvent une source de frustration. L'un de ses problèmes est qu'on ne peut souvent pas lui faire confiance : l'information dont vous avez besoin peut être manquante, obsolète voire fallacieuse. Dans ce livre, il décrit les concepts et les idées à la base d'une documentation vivante, et utilise des exemples pratiques sur la façon de créer une documentation toujours à jour.

Pour lui, la documentation concerne la connaissance. Nous extrayons la connaissance et la transférons lors de conversations avec d'autres personnes, mais nous en gagnons aussi de nos « conversations » avec les machines, en écrivant du code, en lançant des tests qui réussissent ou qui échouent, en utilisant l'UI d'une application et en vérifiant la réponse qu'elle nous retourne. L'observation constitue une troisième voie pour acquérir de la connaissance. Vous apprenez en regardant comment les gens travaillent et se comportent dans différentes situations, en écoutant leurs conversations entre eux.

La connaissance est nécessaire pour éviter de perdre du temps à trouver des réponses à des questions auxquelles nous devrions déjà savoir répondre. Nous avons aussi besoin d'elle pour éviter des décisions sous-optimales qui pourraient potentiellement mener à de la dette technique et à des coûts de développement et de maintenance accrus. Cyrille Martraire fait ressortir le fait que la plupart de la connaissance est déjà présente, dans le code source, les tests, le fonctionnement de l'application, mais aussi dans les têtes de toutes les personnes y travaillant. Il s'agit essentiellement de la trouver et de l'exploiter.

Dans la première partie du livre, il décrit les quatre principes au cœur d'une documentation vivante : elle est fiable, nécessite peu d'effort, elle est collaborative et révélatrice. Une documentation vivante permet aux développeurs de se concentrer sur la qualité de leur travail tout en créant la documentation.

Au fil de plusieurs chapitres, il décrit des façons d'extraire des pans importants de connaissance d'un système, comment créer une documentation toujours à jour avec un coût minimal, y compris sous forme de documents traditionnels. Puisqu'une documentation vivante doit évoluer au même rythme que le système, elle est normalement créée de manière automatisée. Les annotations et les conventions sont deux approches qui permettent cela. Un glossaire des termes utilisés dans un sous-ensemble d'un système est un exemple de document qui peut être automatiquement extrait du code source. La connaissance, ainsi que la documentation, peuvent aussi être construites à partir d'un système en cours d'exécution. Pour mieux comprendre un domaine, les développeurs travaillant sur une application devraient l'utiliser et apprendre son comportement à partir de ses cas d'utilisation les plus courants, y compris dans des domaines compliqués. Inspecter un système distribué en temps réel et agréger les traces dans un graphe de dépendance de service peuvent être d'un grand secours pour les architectes dans la compréhension exacte du fonctionnement de celui-ci.

Dans les derniers chapitres, Cyrille Martraire explique comment une documentation vivante peut aider à la conception et à l'architecture d'un système, en particulier pour des équipes qui pratiquent l'architecture évolutive. Pour des équipes travaillant en DDD, avoir des difficultés à générer un glossaire vivant ou toute autre documentation liée à l'entreprise est un signe révélateur que leur façon de travailler en DDD n'est pas correcte et que la conception du code devrait être repensée pour refléter plus exactement le domaine d'affaire. Quand elles utilisent les techniques décrites dans le livre, les équipes commencent souvent à voir d'autres améliorations de conception. Documenter les décisions peut souvent révéler des faiblesses et encourager plus de réflexion et une meilleure conception.

Enfin, il donne des indications pour introduire une documentation vivante dans un nouvel environnement, et des façons de documenter des applications existantes. Il recommande souvent un démarrage lent et en douceur pour introduire la documentation vivante, sans demander d'autorisation. Au lieu de cela, le fait de documenter devrait graduellement devenir une part du travail quotidien des développeurs. Les applications existantes sont souvent assez précieuses, bien que la connaissance à leur sujet ne soit généralement pas facilement accessible. Elles manquent de tests, et il n'y a pas de définition claire de leur comportement. Pour surpasser cela, Cyrille Martraire décrit quelques techniques qui s'appliquent particulièrement aux systèmes existants.

InfoQ : Parlez-nous un peu de ce livre.

Cyrille Martraire : Ce livre est le résultat de plusieurs années passées à collecter des idées et à essayer des choses sur la documentation dans un environnement agile. La documentation a toujours été une source de frustration pour les personnes travaillant dans le développement logiciel. Elle n'est jamais « comme elle devrait être », quoi qu'on veuille dire par cela. Il est temps que nous résolvions ce problème avec des réponses concrètes et applicables afin de pouvoir vivre en paix avec cela, et d'être plus efficace dans le développement logiciel en même temps.

Ce livre permet donc de partager la connaissance efficacement, d'être plus efficace, collectivement et dans la durée, pour développer et faire évoluer du logiciel. Ce qui veut dire qu'il s'agit aussi d'un livre déguisé sur la conception logicielle.

InfoQ : Pourquoi avez-vous décidé d'écrire ce livre ?

Cyrille Martraire : Le facteur déclencheur a été le retour enthousiaste après mes conférences lorsque j'ai mentionné des techniques de documentation peu familières. En tant que développeur au sein de nombreuses sociétés, j'ai passé pas mal d'années à expérimenter des techniques de documentation pour rendre la bonne conception logicielle visible, et pour encourager une meilleur conception. Le livre a été une conclusion naturelle pour partager cela de façon structurée.

InfoQ : À qui ce livre s'adresse-t-il ? Que sont censés apprendre ses lecteurs ?

Cyrille Martraire : Ce livre est pour les professionnels du logiciel qui n'ont pas peur de quelques lignes de code. Idéalement, des leaders techniques, des architectes logiciels et des testeurs spécialisés en automatisation. Ils apprendront comment faire de la documentation de façon novatrice, sans trop de prose et avec des techniques sympas à mettre en place. Des lecteurs m'ont dit avoir appris plus que cela !

InfoQ : Voyez-vous une valeur business dans la documentation vivante ?

Cyrille Martraire : Oui, il s'agit d'accélérer la livraison. On passe trop de temps dans les équipes logicielles à redécouvrir comment ce code a été conçu, ce qu'il fait, et comment le faire évoluer de façon cohérente.

InfoQ : Quels sont les avantages principaux que vous voyez pour les équipes ou les organisations qui adopteraient une documentation vivante ?

Cyrille Martraire : Elles travaillent plus vite, comme je viens de le dire, et elles limitent aussi la dégradation du code. Quand vous savez comment une chose a été conçue, vous pouvez respecter cette conception, ou la modifier en ayant une connaissance complète du contexte. C'est stimulant. Et il y a autre chose : dès lors que vous prêtez attention à la documentation de ce que vous faites, vous avez tendance à le faire mieux. Cela compte beaucoup !

InfoQ : Quels sont les principaux défis que vous voyez ?

Cyrille Martraire : Un premier défi de la documentation, c'est qu'il ne s'agit pas du sujet le plus excitant qui soit de prime abord. Mais avec la documentation vivante, cela devient beaucoup plus amusant, jusqu'à ce que ça devienne un problème en soi, une nouvelle opportunité de procrastiner et d'éviter de faire votre travail ennuyeux.

InfoQ : En travaillant avec une documentation vivante, vous restez très proche du code. Est-ce que les experts métier et d'autres personnes ne faisant pas partie du noyau de l'équipe peuvent aider à l'adoption et au maintien de la documentation vivante ?

Cyrille Martraire : Il est vrai que les pratiques de documentation vivante tendent à favoriser la proximité de la connaissance au code comme source de vérité. Cependant, la « collaboration » est un ingrédient clé d'une documentation vivante, aussi proposons-nous de nombreuses techniques pour s'assurer que la connaissance appropriée soit accessible à toutes les personnes impliquées, en particulier les non techniques. Par exemple, des glossaires et des diagrammes vivants sont automatiquement générés à partir du code. Alors oui, c'est pour tout le monde, pas uniquement pour le développeur qui commite une amélioration dans la base de code après une discussion collective.

InfoQ : Voyez-vous un besoin, ou un avantage, de bibliothèques avec des annotations recommandées, voire incluses dans un langage ou une plate-forme, par exemple une bibliothèque d'annotation DDD ?

Cyrille Martraire : Une telle bibliothèque réutilisable aurait un avantage indéniable, si tant est que vous puissiez en créer une qui corresponde à la façon de programmer particulière de chacun et aux technologies spécifiques. Jusqu'ici, je préconise plutôt d'élaborer votre propre bibliothèque au sein de votre société, département ou équipe. Si vous pratiquez la programmation fonctionnelle et le DDD en Java, par exemple, vous auriez alors votre propre bibliothèque d'annotations Java. Mais si vous pratiquez l'Event Sourcing avec un framework basé sur les annotations, de nombreuses annotations existent déjà, vous n'avez pas besoin d'y ajouter grand-chose. Et si vous ne faites rien de cela, une bibliothèque qui gérerait tout cela paraîtrait un peu exotique à votre équipe.

InfoQ : Pensez-vous qu'un jour la documentation vivante fera partie du courant dominant de la communauté logicielle ?

Cyrille Martraire : Les techniques vont bien sûr devenir mainstream, la question est de savoir si le terme « Documentation vivante » le sera aussi. Mais c'est un sujet secondaire :) (rire)

InfoQ : Quelles sont les raisons principales qui entravent l'adoption de la documentation vivante dans la communauté logicielle ?

Cyrille Martraire : La documentation en général a été un sujet négligé depuis des lustres. Le Manifeste agile a souvent aussi été mal interprété. Il n'a jamais dit de ne plus faire de documentation. Mais les techniques qui réconcilient les objectifs de la documentation avec les valeurs agiles ne sont pas très connues. Ce livre a pour but de combler ces lacunes !

Au sujet de l'auteur

Cyrille Martraire est une autorité reconnue de la conception pilotée par le domaine et du craftsmanship logiciel. Il intervient régulièrement lors de grandes conférences internationales. Doté d'une connaissance approfondie du financement sur les marchés de capitaux, il a travaillé et dirigé de nombreux projets significatifs. Il est CTO et co-fondateur d'Arolla, une société de conseil française spécialisée dans le développement logiciel.