Une documentation efficace est indispensable à tout labo de recherche qui veut standardiser ses analyses et garder un fonctionnement fluide. Si vous n'êtes pas convaincu de son importance, pensez à ceci : sans elle, votre équipe risque d'avoir du mal à comprendre et à utiliser votre code, ce qui fait perdre du temps et la rend de plus en plus dépendante de vous.
Qui la lit
Mais créer et organiser une documentation efficace ne se résume pas à écrire des instructions. Il faut aussi comprendre qui va la lire et ce que ces personnes cherchent. Dans un labo, il est utile de penser à deux « personas » principaux :
- Le nouvel arrivant : un nouveau doctorant, postdoc ou chercheur qui rejoint le labo et doit se mettre rapidement à niveau sur votre code et vos analyses. Il cherchera sans doute des instructions claires, pas à pas, pour utiliser votre code, ainsi qu'une vue d'ensemble de sa structure et de son organisation.
- Le membre expérimenté : quelqu'un qui est au labo depuis un moment et connaît déjà votre code. Il cherchera plutôt des informations avancées, comme le détail de certaines fonctions ou de certains modules, ou de l'aide pour résoudre un problème.
Dans la partie suivante, nous verrons quelques techniques concrètes pour créer et organiser une documentation qui serve efficacement ces deux publics.
HenryHenry, nouveau stagiaire au labo, doit parcourir la documentation pour comprendre les grandes idées des recherches de l'équipe. Son objectif : installer sur son ordinateur tous les outils dont il aura besoin ensuite.
MagalieChercheuse confirmée, Magalie cherche comment utiliser une méthode déjà développée par le labo pour prétraiter ses données. Elle veut surtout connaître les paramètres disponibles et le type de résultat produit par la méthode.
Quoi écrire
Pour bien organiser et présenter l'information, il est utile de découper la documentation en plusieurs parties qui répondent à des objectifs différents.
Ces parties peuvent être :
- How-to : des instructions pas à pas pour réaliser une tâche précise.
- Tutoriels guidés : un accompagnement plus approfondi pour utiliser le logiciel ou le paquet, en général sous forme d'une série d'exemples ou d'exercices.
- Description de l'API : la description détaillée des fonctions, méthodes et autres composants qui constituent le logiciel ou le paquet.
Il peut aussi être utile d'ajouter une partie à part sur les instructions d'installation, pour que les nouveaux utilisateurs sachent par où commencer.
En découpant ainsi l'information, chacun trouve facilement ce qu'il cherche. Par exemple, Henry peut suivre les instructions d'installation et les tutoriels guidés pour comprendre ce que fait l'équipe, tandis que Magalie peut aller directement à la description de l'API pour la définition d'une méthode, et au How-to pour ses questions précises sur le traitement de ses données.
Comment la tenir à jour
Maintenant que nous savons quoi écrire, il faut réfléchir à la façon de rendre la documentation facile d'accès. Une documentation exacte et à jour est essentielle pour donner aux utilisateurs l'information dont ils ont besoin, mais l'entretenir peut prendre beaucoup de temps.
Une solution consiste à générer la documentation avec Sphinx puis à l'héberger sur une plateforme comme readthedocs.org, qui propose un hébergement gratuit pour les projets open source. Les utilisateurs y accèdent facilement, et le projet gagne en visibilité. Pour alléger la charge, il est recommandé d'automatiser la génération de la documentation, en l'intégrant au pipeline du projet pour qu'elle se mette à jour automatiquement à chaque commit, fusion ou nouvelle version.
Autre façon de garder la documentation à jour : régénérer ses parties les plus importantes à chaque build. Par exemple, le How-to peut être régénéré en relançant une série de notebooks avec la dernière version du paquet. Les exemples restent ainsi exacts et exécutables. De même, la description de l'API peut être régénérée à partir du code à chaque nouvelle version, pour rester toujours synchronisée avec le logiciel. La documentation reste juste et utile pour l'utilisateur, avec moins de travail pour la personne qui la maintient.
En résumé, une documentation claire et à jour est indispensable pour donner à votre équipe l'information dont elle a besoin. Avec une structure pensée pour les différents publics du labo et une génération automatisée, la documentation devient facile d'accès pour tous, sans alourdir le travail de maintenance.
Un exemple
Par exemple, la documentation que j'ai écrite pour le labo Kloosterman suit la structure décrite dans cet article ; elle est consultable sur https://kloostermannerflab.bitbucket.io. Elle est générée avec Sphinx et mise à jour automatiquement à chaque nouvelle version du paquet Python fklab, pour être toujours à jour. Une version « develop » est aussi mise à jour à chaque commit. Le site est découpé en parties qui répondent à des objectifs différents, avec des instructions pas à pas, des explications approfondies et une description détaillée de l'API.
Elle a fait ses preuves pendant trois ans, en aidant les étudiants à gagner en autonomie et en rapidité dans leurs analyses.
Une anecdote
Petite anecdote : j'ai eu du mal, un temps, à faire lire à mon équipe la documentation que nous avions créée. Ils avaient l'habitude de regarder directement le code ou de demander autour d'eux, et ne voyaient pas l'intérêt de prendre le temps de la lire. Puis j'ai eu une idée : j'ai bloqué un créneau de réunion et ajouté un jeu dans la documentation, une sorte de chasse au trésor, avec des énigmes et des indices cachés dans les parties les plus importantes. Et vous savez quoi ? Ça a marché ! L'exercice était plus engageant et plus amusant, et à la fin, l'équipe connaissait mieux la documentation et s'en servait bien plus efficacement.