La documentation est encore trop souvent considérée comme superflue ou comme une contrainte. Adopter une approche de Documentation-as-Code représente au contraire un potentiel gain de temps et d’efficacité pour les équipes en contexte Agile, en particulier pour assurer la continuité du code et de l’infrastructure logicielle.
1. Et si la documentation faisait partie du code source ?
Dans un contexte Agile, la documentation est souvent un sujet délicat. En s’appuyant sur deuxième principe du Manifeste Agile : « Un logiciel fonctionnel plutôt qu’une documentation complète », certains la considèrent en effet comme contre-productive. Pourtant, ce principe ne signifie à mon sens pas qu’il ne faut pas de documentation, mais plutôt que « il ne faut pas sacrifier la qualité du logiciel pour la produire. »
L’objectif de l’équipe est bien sûr avant tout de produire le logiciel, et celui des membres recrutés plus tard de maintenir et de modifier ce logiciel. Mais comment pourraient-ils y parvenir sans documentation ? On peut répondre que le code en lui-même doit suffire à comprendre l’essentiel… mais même quand le nom des objets est explicite et bien choisi cela est loin d’être suffisant. Néanmoins, le problème est que produire et maintenir la documentation prend beaucoup de temps. Une solution pourrait alors être de considérer la documentation comme faisant partie du code source.
2. Documenter les bonnes pratiques
Mais avant de parler du concept de Documentation-as-Code, j’aimerais partager une expérience personnelle qui, je pense, pourra vous sembler familière. Un éditeur de solution bancaire employant à la fois des prestataires et des internes avait connu un fort turn-over en un temps très court. Appliquant le principe que la documentation n’est écrite que si plusieurs personnes la réclament, elle était pratiquement inexistante. Or, lors du départ de plusieurs membres de cette équipe, il y avait bien sûr eu un transfert de connaissances mais court et insuffisant.
Par manque de connaissance de l’architecture logicielle et de l’infrastructure, la nouvelle équipe a alors rencontré de nombreuses difficultés pour modifier le code source. Bien que l’application ait été réputée avoir été suffisamment testée, il s’est avéré que certains tests unitaires échouaient mais ne bloquaient pas la release, et que les tests fonctionnels automatisés étaient pour la plupart désactivés. Conséquence évidente : une grande difficulté à sortir des releases car la plupart des changements produisaient des effets de bord sur l’application, introduisant des bugs ou des régressions. Le contenu même des releases était flou, la release note étant vague et souvent incomplète. Si l’on ajoute à ça la pression du management, l’ambiance de travail et le moral de l’équipe se sont dégradés, contribuant à réduire encore sa capacité à implémenter les fonctionnalités.
Il a alors été nécessaire de mettre en place un projet de réduction de la dette technique, qui est notamment passée par l’instauration de nouvelles bonnes pratiques. Les principales actions menées ont été :
- L’automatisation de la génération des schémas d’architecture, à partir de fichiers markdown dans le référentiel git, pour être facilement accessible aux développeurs.
- La génération de rapports de test, et leur affichage dans un tableau de bord pour les rendre visibles.
- La mise en place d’un template pour les messages de commit et la génération automatique des release notes pour pouvoir vérifier ce qui est livré.
- La rédaction d’une convention de codage et la mise en place de l’analyse statique pour s’assurer que ces règles sont respectées ; ainsi que la production automatique d’un rapport d’analyse de la qualité du code.
Ces bonnes pratiques ont permis à l’équipe de réussir à livrer à nouveau, à mesure qu’elles étaient mises en place, pour finalement résorber la dette technique. Surtout, la confiance et un climat favorable au travail ont pu être rétablis.
3. La Documentation-as-Code ou DaC
On peut alors parler de Documentation-as-code, ou DaC ou encore de Doc-as-Code. Mais comment définir le DaC ? Nous pouvons le faire par les pratiques qui utilisent les techniques de codage appliquées à la documentation :
- Git
- Code/markdown
- Revues
- Tests
- Suivi des problèmes
Mises en commun, ces pratiques offrent une définition fiable de ce qu’est la documentation. Mais celle-ci peut aussi exister sous plusieurs formes :
- User Stories : c’est de la documentation.
- Code source : c’est une documentation si elle est bien nommée et suit les standards de codage.
- Tests du code source : les tests unitaires du code source sont de la documentation… si les tests sont expliqués et que leurs limites sont spécifiées.
- Plan de test et résultats des tests : c’est aussi de la documentation.
- BDD : les fichiers Gherkin (.feature) sont de la documentation vivante.
- X-as-Code (comprendre Configuration-as-Code, Infra-as-Code, Security-as-Code…) : c’est aussi de la documentation vivante. Voici quelques exemples : les playbooks Ansible, les fichiers Terraform tf…
- Les fichiers de configuration, s’ils sont lisibles par les utilisateurs.
Sous cette forme, la Documentation-as-Code présente plusieurs avantages majeurs :
- La documentation vraiment utile est maintenue à jour tout en demandant un minimum de travail.
- La documentation est ramenée plus tôt, comme on le fait avec les tests (on parle de « left-shift »).
- Les connaissances sont partagées.
4. La DaC : 4 caractéristiques et 4 pratiques
On peut reconnaître quatre caractéristiques essentielles à la Documentation-as-Code :
- Objectif : chaque documentation doit avoir un objectif.
- Simplicité : la documentation doit rester simple.
- Stabilité : la documentation doit être stable, c’est-à-dire qu’il ne faut la créer ni trop tôt ni trop tard.
- Exécutable : la documentation doit être exécutable lorsque cela est possible, en se basant sur des tests.
En parallèle de ces 4 caractéristiques, on peut aussi identifier 4 pratiques de la Documentation-as-Code :
- Créer une documentation vivante (ou exécutable) le plus tôt possible.
- Documenter le « pourquoi » et non le « comment ».
- Mettre à jour la documentation lorsque le code est mis à jour.
- Rendre la documentation visible.
Zoom sur les outils de documentation
De multiples outils d’automatisation peuvent servir à produire la documentation. Voici quelques exemples en open source :
- Doxygen : il produit de la documentation à partir d’annotations dans le code source, stockées dans Git.
- PlantUML : il produit des graphiques à partir de fichiers texte, stockés dans Git.
- AsciiDoctor : il produit des fichiers PDF ou HTML à partir de fichiers markdown, stockés dans Git.
- PicklesDoc : il produit un fichier PDF ou HTML à partir des fichiers BDD .features…
- JUnit Viewer et Allure : ils produisent de la documentation sur les tests (rapports de tests).
- SonarQube : il produit de la documentation sur l’analyse statique (par exemple les rapports d’analyse).
Vous l’aurez compris, la liste est pratiquement infinie.
5. Pour conclure…
Comme nous venons de le voir dans cet article, une bonne part de la documentation est d’ores et déjà disponible : il suffit d’aller la chercher et de la centraliser. Pour le reste, il est possible de simplifier la génération de la documentation et d’automatiser sa production : c’est l’exemple que j’ai donné avec la société d’édition dans un domaine très réglementé. Alors que le poids des tâches de documentation devenait écrasant et démotivait l’équipe, l’automatisation de certaines documentations a permis de réorganiser le travail, d’améliorer le moral de l’équipe et enfin de simplifier le travail de documentation : soit un gain de temps et d’efficacité considérable !
