Pour une documentation toujours plus vivante

Dans mon précédent article, je vous ai parlé de l’utilisation de Gherkin dans la rédaction des cas de test. Gherkin vise à tester le fonctionnel et permet une meilleure lisibilité des cas de test. Mais à quoi sert une bonne lisibilité si personne ne lit ces cas de test ? Si les gens continuent d’aller regarder la documentation (écrite il y a bien longtemps, et potentiellement pas à jour), tout ce beau travail ne sert à rien. Dans ce cas là, pourquoi ne pas regrouper l’étape de spécification et l’étape de conception des tests en une seule étape ? C’est le principe de la documentation vivante.

L’enjeu de la documentation

Avoir une bonne documentation est primordial pour une entreprise : elle représente la connaissance accumulée dans le temps, et sert de pilier dès qu’on se pose une question sur une fonctionnalité créée plusieurs mois auparavant (quel était le but de cette fonctionnalité ? quels étaient ses cas particuliers ? …).

La documentation subsiste aux départs des collaborateurs, et évite que les derniers mois d’un expert ne se transforment en une course pour transmettre tout son savoir aux autres.

L’accueil de collaborateurs est aussi facilitée grâce à une bonne documentation car elle :

donne un support vers lequel le nouvel arrivant pourra se tourner s’il a des questions
donne un socle commun à tout le monde, avec le même vocabulaire
s’assure qu’aucun élément important n’a été oublié pendant l’onboading

Une bonne documentation permet aussi une meilleure transmission des savoirs entre les équipes : tout ne repose pas sur la présence du collaborateur expert de telle ou telle fonctionnalité. On gagne en fluidité et en rapidité (pas besoin de faire une réunion s’il suffit d’ouvrir la documentation).

La documentation peut aussi être un enjeu stratégique. Dès qu’on travaille sur un système critique, la réglementation nous impose un traçage extrêmement précis des exigences entre les différents sous-systèmes afin d’assurer :

qu’aucun besoin n’a été oublié
que toutes les fonctionnalités implémentées répondent au moins à un besoin

Les limites des outils de documentation

Les entreprises ont très bien compris que la documentation était stratégique, mais cela reste un véritable casse-tête à gérer : c’est une activité peu gratifiante et difficile à maintenir au jour le jour (on a tous déjà dit “je mettrai la documentation à jour demain, j’ai une urgence là”, et puis on oublie de le faire le lendemain…).
Mais ce n’est pas tout ! Les outils pour gérer cette documentation sont souvent inappropriés et rendent la tâche encore plus pénible. Voici des exemples d’outils utilisés pour la documentation, et certains de leurs inconvénients :

les fichiers plats (type Word) : inadaptés pour garder un historique clair et centralisé (les gens créent des copies des fichiers pour garder l’historique, puis stockent ces fichiers à différents endroits).
les outils de ticketing (type JIRA) : permettent que tout soit regroupé à un seul endroit, mais la recherche dans l’historique est souvent fastidieuse, les tickets sont souvent mal reliés entre eux, et il est quasiment impossible avec ce genre d’outils d’avoir une documentation représentative de l’état actuel de notre logiciel.
les wikis : permettent de bien regrouper la documentation à un même endroit, et la recherche par mot-clés est fluide. De plus, nous pouvons avoir une idée claire de la spécification de notre outil à tout instant. Mais tout cela dépend de la rigueur et de l’implication des équipes dans la maintenance de cette documentation. Si l’équipe ne joue pas le jeu, alors cette documentation n’est pas à jour, et donc ne sert à rien.

On comprend bien que chaque méthode a ses avantages et ses inconvénients. Mais une chose est sûre : regrouper tous les avantages (documentation à jour, centralisée, avec gestion de l’historique) est extrêmement difficile. Du coup, notre première envie lorsqu’il faut aller chercher une information dans la doc’ est souvent de tout jeter et recommencer à zéro.

La documentation vivante

L’objectif de la documentation vivante est d’avoir une documentation à jour à chaque instant. Pour arriver à cet objectif, il faut imposer aux équipes de mettre à jour cette documentation au travers des tests automatisés. Les tests ne sont plus uniquement une barrière à la sortie, ils deviennent la spécification elle-même. Les tests et la spécification ne font plus qu’un.

Le processus d’implémentation d’une fonctionnalité n’est plus un format en cascade, où la spécification n’est jamais mise à jour une fois le code implémenté :

Nous passons à un format où le code et la spécification s’alimentent l’un l’autre perpétuellement :

Pour que cette méthode marche correctement, il est recommandé d’utiliser le langage Gherkin. La lisibilité de Gherkin permet que tout le monde, et en particulier le PO, soit capable de mettre à jour les cas de test. Une fois ces cas de test mis à jour, le développeur et le QA prennent la main pour respectivement implémenter la fonctionnalité, et adapter les tests automatisés. La documentation, au travers des tests automatisés, évolue en même temps que le code de l’application, et n’est donc jamais obsolète.

Bien évidemment, nous conservons les atouts classiques des tests automatisés qui permettent de détecter si une régression apparaît dans l’application. Le petit bonus vient du fait que les bugs trouvés par les tests automatisés sont plus simples à interpréter puisque les cas de test sont lisibles (il n’y a pas besoin d’être expert de la codebase de test pour comprendre ce qui a cassé).

De part sa nature, on constate assez vite que la documentation vivante permet de répondre aux différents problèmes des outils traditionnels de documentation :

une documentation centralisée dans la codebase
une bonne gestion de l’historique grâce aux outils performants des développeurs, comme Git
une documentation à jour car la spécification et les tests sont imbriqués.

Utilisation du Test Driven Development

Le Test Driven Development (TDD) est le prolongement logique de la documentation vivante. Voyez le comme la cerise sur le gâteau…

Le TDD consiste à écrire d’abord les tests, puis la fonctionnalité. Il s’oppose aux pratiques traditionnelles de développement où on implémente la fonctionnalité d’abord, puis les tests. Avec le TDD, on obtient un développement en 3 étapes :

implémenter les tests (qui doivent échouer puisque la fonctionnalité n’a pas été implémentée, ou mise à jour)
implémenter la fonctionnalité minimale pour que le tests passent
optimiser l’implémentation tout en s’assurant que les tests continuent de passer

Il existe de nombreux avantages au TDD, dont :

les tests sont toujours implémentés (alors que souvent, ils sont oubliés)
le logiciel présente moins de bugs car tout refacto est testé directement
on code plus vite : cela nécessite un peu d’expérience et de pratique, mais notre code est plus incrémental et nous avons une meilleure confiance en lui grâce aux tests

Etant donné que les scénarii de test sont déjà rédigés lorsqu’on applique la documentation vivante, il ne manque qu’un pas pour appliquer les principes du TDD…

Contraintes et limites

Je tiens à préciser que je n’ai jamais eu l’occasion de mettre en place la documentation vivante dans une entreprise. Si la démarche est particulièrement séduisante à première vue, j’imagine qu’il existe quelques difficultés à une telle pratique.

Tout d’abord, il est nécessaire que les tests soient intégrés à la CI (Continuous Integration). Cette étape peut sembler évidente, mais il existe des situations où les tests sont lancés par des bots (via Slack par exemple), ou encore par les QA uniquement. Si les tests ne sont pas intégrés à la CI, nous n’avons aucune assurance que les tests soient lancés à chaque update du code, et donc que la spécification soit mise à jour.

Il faut aussi que le PO et le QA travaillent étroitement ensembles pour rédiger des cas de tests pertinents d’un point de vue métier, et implémentables facilement. Cette étape de synchronisation peut être chronophage : la rédaction de cas de test en Gherkin n’est pas aussi simple qu’elle en a l’air.

Certains outils de génération de documentation vivante sont trop simples, et ne permettent pas de facilement catégoriser et hiérarchiser les tests. On se retrouve alors avec une documentation immense mais non exploitable car la navigation est très fastidieuse.

Enfin, et c’est sûrement le point le plus essentiel, la mise en place d’une stratégie de documentation vivante est un changement de paradigme complet : elle va bien au-delà du simple périmètre de l’équipe technique. Sa mise en place est lourde, et le retour sur investissement peut n’arriver qu’après plusieurs mois d’efforts et d’adaptations.

Tout le monde doit avoir accès à cette documentation, et y trouver son intérêt : les POs doivent apprendre à rédiger des spec’ suivant Gherkin ; les commerciaux peuvent s’en inspirer pour rédiger les tutoriels pour les clients ; le support doit apprendre à y naviguer, etc…

Aussi, il est impératif d’avoir un appui du top management pour se lancer dans ce chantier !

Et vous, avez vous déjà testé et/ou mise en place la documentation vivante ? N’hésitez pas à partager en commentaires vos retours d’expérience !

Ce qu’il faut retenir

La documentation doit
- être centralisée
- avoir une gestion de l’historique
- être à jour et représentative du logiciel à chaque instant
La documentation vivante consiste à regrouper les tests et les spécification : les tests et la spécification ne font plus qu’un
Fortement conseillé de la rédiger avec Gherkin
Changement complet de paradigme de l’entreprise