Dans un monde où l’information est essentielle, la documentation d’un produit joue un rôle crucial.
Un produit qui ne dispose pas de sa notice n’est pas considéré comme un bon produit, de même qu’un projet sans documentation n’est pas considéré comme un bon projet.
La gestion des versions de la documentation est d’une importance capitale au sein d’un projet, d’autant plus qu’il peut y avoir des modifications majeures entre les différentes versions. Une bonne gestion de la documentation permet non seulement aux utilisateurs, mais également aux contributeurs, d’avoir des informations correctes et à jour pour chaque version du projet.
Dans cet article, nous allons partager avec vous les problématiques que nous avons rencontrées autour de la documentation sur notre projet SaagieAPI ainsi que nos réflexions et pistes d’améliorations.
Documentation de Saagie API : historique et problématique
Qu'est ce que SaagieAPI?
SaagieAPI est une librairie développée en Python dont le but est de faciliter les interactions avec la plateforme Saagie. Cette dernière est une plateforme DataOps qui permet d’orchestrer vos projets data grâce à des jobs et des pipelines.
Évolution de la documentation de la librairie SaagieAPI
Lors de la création de la librairie SaagieAPI, nous n’avions pas pris en compte la documentation. Par conséquent, nous ne disposions d’aucune documentation à fournir aux contributeurs et aux utilisateurs.
Cette approche a rapidement posé des problèmes aux différents contributeurs du projet. Pour remédier à cela, nous avons décidé d’intégrer une documentation technique directement dans le code, en utilisant des docstrings.
Une fois cette étape franchie et grâce aux retours des contributeurs et des utilisateurs, nous avons travaillé sur une documentation plus orientée métier, afin de faciliter l’utilisation de la librairie. Pour ce faire, nous avons opté pour l’utilisation de la fonctionnalité wiki fournie par Github au sein du repository. Cela nous a permis de regrouper le code et la documentation de la librairie au même endroit, mais sans lien fort entre les deux.
Mais le wiki ne permet d’exposer qu’une seule version de la documentation. Lors de la mise en place de la documentation, ce mode de fonctionnement convenait à notre projet, car celui-ci comportait un nombre limité de contributeurs et d’utilisateurs.
Cependant, avec l’augmentation du nombre d’utilisateurs et des versions différentes de la librairie, le fonctionnement du wiki ne permettait pas de fournir une expérience satisfaisante aux utilisateurs.
De plus, l‘absence de lien fort entre le code et la documentation posait problème dans notre processus de travail. En effet, le fait que la documentation soit décorrélée du code entraînait des oublis d’ajouts ou de modifications de la documentation lors des actions sur le code de la librairie.
Pour résoudre ces problématiques, il nous est apparu essentiel de fournir une documentation versionnée à nos utilisateurs. Cela leur permet de consulter avec certitude la documentation correspondant à la version utilisée de la librairie, favorisant ainsi leur autonomie.
Besoin et solution : un nouvel outil, Read the Docs !
Suite au constat que nous avions fait, il nous paraissait important que notre outil de documentation réponde à ces 2 critères :
- Avoir de la documentation versionnée
- Pouvoir gérer la documentation comme du code.
Suite à cela, nous avions cherché un nouvel outil puisque le wiki de Github ne répondait plus à nos critères et nous avions trouvé les outils suivants : Gitbook, Confluence, Read the Docs.
Notre préférence pour les outils open source nous a orienté vers Read the Docs tout comme l’hébergement gratuit pour les projets public qu’il propose.
Qu’est-ce que Read the Docs ?
Read the Docs propose plusieurs formats de documentation : rst (reStructuredText) et Markdown.
Il intègre également plusieurs générateurs de documentation : Sphinx (rst et Markdown) et Mkdocs (Markdown).
Pour la création des différentes versions de documentation, Read the Docs liste les branches et/ou tags de votre repository et vous laisse sélectionner ceux qui vous conviennent.
Pour plus d’informations, vous pouvez consulter la documentation de Read the Docs
Optimiser la création de son projet avec Read the Docs
Pour vérifier la valeur apportée par une documentation versionée ainsi que la facilité d’implémentation proposée par Read The Docs, nous avons décidé de réaliser un POC. Celui-ci a été mené sur une journée.
Étape 1: Configuration du projet
- Premièrement, nous avons créé un fork (une copie) de notre projet officiel.
- Nous avons par la suite créé un compte sur Read The Docs
- Nous avons conclu la configuration du projet par la création d’un lien entre Read The Docs et le projet forké
Étape 2: Migration de la documentation existante
- Nous avons profité du POC pour essayer un nouveau découpage de la documentation. Nous sommes passé d’une page par classe d’objet à une page par fonction.
- Adaptation de la documentation existante au format Markdown vers le format rst. Cette étape aurait pu être évitée si nous avions utilisé le générateur de documentation Mkdocs. Pour cette étape fastidieuse, nous avons également utilisé des convertisseurs en ligne afin de nous aider et de gagner du temps.
Étape 3: Tests
- Notre premier test avait pour but de vérifier la capacité de Read The Docs a proposé une documentation versionnée basée sur des tags et non sur des branches. En effet, notre projet officiel utilise les tags pour définir ses différentes versions.
- Ensuite, nous avons testé la fonctionnalité de compilation automatique suite à une action réalisée sur le repository Git hébergeant le projet de test.
Étape 4: Validation du POC
- Après nos tests et à l’issue de notre journée de POC, nous avons présenté le résultat de ce dernier à l’ensemble de l’équipe.
- Après la présentation, nous avons validé collectivement le POC.
- Suite à la validation de l’équipe, nous avons commencé les implémentations nécessaires au passage en production
Étape 5: Utilisation en prod
- Depuis la mise en production de Read The Docs, chaque nouvelle version contient la documentation associée aux nouveautés et est vérifiée comme le code lors des demandes d’intégration (merge request). Cela nous a permis d’éviter les oublis dans la documentation mais également de gagner en qualité.
Conclusion du projet
Comme vous avez pu le constater, nos besoins autour de la documentation ont changé avec le temps et les évolutions du projet SaagieAPI.
La gestion de la documentation est une étape essentielle pour tout projet et qui doit être prise en compte tout au long du cycle de vie de celui-ci pour répondre à vos besoins et celui de vos utilisateurs.
Toutefois, il n’existe pas de solution unique et immuable pour votre documentation.
La solution idéale pour votre projet doit répondre aux questions suivantes :
- Quel niveau de documentation est utile au bon fonctionnement de mon projet ?
- Est-ce qu’une documentation technique est suffisante ?
- Doit-on ajouter une documentation métier ?
- Y a-t-il plusieurs versions de mon projet qui cohabitent ?
- À quel rythme évolue votre projet et donc ses besoins en documentation ?
- Est-ce que la documentation de votre projet doit évoluer en même temps que celui-ci ? ou doit-elle avoir un cycle de vie séparé ?
