Vous venez de terminer un pipeline de simulation. Vos résultats sont prêts à être publiés. Votre code fonctionne. Alors pourquoi avez-vous encore besoin de le documenter ?
Parce que sans documentation, votre logiciel est plus difficile à citer, plus difficile à reproduire et plus difficile à entretenir. Les collaborateurs peuvent ne pas comprendre comment l’exécuter. Les futurs étudiants ne savent peut-être pas quel fichier de configuration est important. Même si vous oubliez peut-être les principales décisions de conception après plusieurs mois.
La documentation n’est pas un complément intéressant pour les logiciels de recherche. C’est le pont entre un outil de travail et un atout de recherche reproductible. Vous n’avez pas besoin d’être un rédacteur technique pour bien le faire. Vous avez besoin d’une structure.
Points à retenir clés
- La documentation fait partie de la recherche reproductible. Le code sans documentation devient une boîte noire que seul son auteur d’origine peut maintenir.
- Quatre types de documentation répondent à quatre besoins d’utilisateurs différents : des didacticiels pour l’apprentissage, des guides pratiques pour faire, des références pour la description et des explications pour la compréhension.
- Le cadre Diátaxis est un moyen pratique d’organiser la documentation des logiciels de recherche.
- Les dix règles simples pour documenter les logiciels scientifiques fournissent une liste de contrôle utile pour rédiger une meilleure documentation.
- Des modèles et des outils existent déjà. Lisez-moi les structures, les fichiers
CITATION.cff, Sphinx, MkDocs et Read the Docs rendent le processus plus efficace.
Pourquoi la documentation est importante
Les logiciels de recherche se situent entre la science et l’ingénierie. Contrairement aux équipements de laboratoire traditionnels, les logiciels peuvent être partagés, modifiés, réutilisés et cités par toute personne ayant le bon environnement. Mais ce potentiel signifie peu si personne ne comprend comment fonctionne le logiciel.
Les enjeux sont pratiques :
- reproductibilité. Sans documentation, d’autres chercheurs ne peuvent pas vérifier ou réutiliser de manière fiable votre travail.
- Citation. Les logiciels qui manquent de conseils et d’instructions d’utilisation sont moins susceptibles de recevoir un crédit approprié.
- Entretien. Lorsqu’un chercheur quitte un laboratoire, le code non documenté devient souvent une dette technique pour la personne suivante.
Une bonne documentation facilite l’utilisation, l’extension, la révision et la préservation des logiciels. Cela réduit également le nombre de questions répétées des collaborateurs et des futurs utilisateurs.
Ce guide vous donne un cadre et des modèles pratiques pour documenter efficacement les logiciels de recherche.
Le cadre Diátaxis : quatre types de documentation
Si votre documentation se trouve actuellement dans un long fichier Lisez-moi, cela peut sembler désorganisé. Les didacticiels, les notes d’installation, les détails de l’API, la théorie, les exemples et le dépannage peuvent facilement se mélanger.
Le cadre de Diátaxis résout ce problème en séparant la documentation en quatre types distincts. Chaque type répond à un besoin différent de l’utilisateur.
1. Tutoriels
Un didacticiel est orienté vers l’apprentissage. Il amène un débutant à un cheminement guidé et l’aide à atteindre un résultat concret.
Exemple : « Configurez FIPY pour votre première simulation de champ de phase. »
Un tutoriel Réponses : Comment apprendre à utiliser ce logiciel ?
2. Guides pratiques
Un guide pratique est orienté vers l’action. Cela aide quelqu’un à accomplir une tâche spécifique après avoir déjà compris les bases.
Les exemples incluent :
- Comment exécuter une simulation de Monte Carlo avec Fipy.
- Comment résoudre les erreurs de convergence.
- Comment exporter les résultats de la simulation au CSV.
A Guide pratique Réponses : Comment puis-je accomplir une tâche spécifique ?
3. Référence
La documentation de référence est orientée vers l’information. Il est factuel, neutre et complet. Il décrit ce que le logiciel fournit sans enseignement ni persuasion.
Les exemples incluent :
- Documentation de l’API.
- signatures de fonctions.
- Spécifications des paramètres.
- Définitions des classes.
Documentation de référence Réponses : à quoi cela sert-il ?
4. Explication
L’explication est orientée vers la compréhension. Il fournit un contexte, un contexte, un raisonnement et une justification de la conception.
Les exemples incluent :
- Pourquoi le solveur utilise un pas de temps implicite.
- Le modèle mathématique derrière la mise en œuvre.
- Pourquoi une stratégie de maillage a été choisie plutôt qu’une autre.
Réponses d’explication : Pourquoi cela fonctionne-t-il de cette façon ?
Les dix règles simples pour documenter les logiciels de recherche
Les dix règles simples pour documenter les logiciels scientifiques constituent une liste de contrôle pratique pour la qualité de la documentation. Ils sont utiles car ils se concentrent sur les habitudes que les chercheurs peuvent appliquer sans créer un service de documentation complet.
Règle 1 : Écrivez des commentaires au fur et à mesure de votre code
Les commentaires doivent expliquer les idées et le raisonnement derrière l’algorithme, et non pas simplement répéter ce que le code dit déjà.
# Good: explains why this approach is used
# Use implicit time stepping for stiff reaction terms to avoid
# timestep restrictions that would make the simulation impractical.
solver = ImplicitTimeStepping(reaction_terms)
# Bad: repeats the line without explaining intent
solver = ImplicitTimeStepping(reaction_terms) # creates solver
Règle 2 : Inclure de nombreux exemples
Des exemples montrent aux utilisateurs comment le logiciel fonctionne dans la pratique. Fournissez des exemples exécutables qui illustrent le flux de travail principal.
Si la documentation est trop encombrée d’exemples, déplacez-les dans un répertoire dédié examples/ et associez-les à partir de la documentation principale.
Règle 3 : Incluez un guide de démarrage rapide
Un guide de démarrage rapide devrait permettre à quelqu’un d’utiliser le logiciel quelques minutes après son téléchargement. Cela devrait inclure une installation, un exemple minimal et une sortie attendue.
Sans un démarrage rapide, de nombreux utilisateurs supposent que le logiciel est trop difficile à utiliser et à partir avant de le tester.
Règle 4 : Rédigez un fichier Lisez-moi
Supposons que le readme sera la seule documentation lue par de nombreux utilisateurs. Il devrait couvrir clairement l’essentiel.
Un README fort devrait inclure :
- Une brève description du projet.
- Instructions d’installation et dépendances.
- Un exemple de démarrage rapide.
- Informations sur la licence.
- Instructions de citation.
- Un lien vers une documentation complète.
Modèle de lecture :
# Project Name
Short description: one sentence explaining what the software does.
## Installation
1. Clone this repository.
2. Run `pip install -e .` or your preferred install command.
3. Verify the installation:
```python
import mypackage
print(mypackage.__version__)
```
## Quickstart
```python
from mypackage import MySimulator
sim = MySimulator(config="default.yaml")
results = sim.run()
```
## Documentation
Full documentation: [Read the Docs link]
## Citation
Please cite this software using the CITATION.cff file.
## License
MIT License
Règle 5 : inclure une commande d’aide pour les CLI
Si votre logiciel dispose d’une interface de ligne de commande, incluez un indicateur clair --help. Il doit expliquer les commandes, les arguments requis, les paramètres optionnels et les exemples.
Les outils Python tels que argparse rendent cela simple.
Règle 6 : Contrôle de version de votre documentation
Conservez la documentation à côté du code dans le contrôle de version. Les utilisateurs de versions de logiciels plus anciennes ont besoin d’un accès à une documentation correspondant à ces versions.
Utilisez l’hébergement de documentation versionné lorsque cela est possible afin que les utilisateurs puissent basculer entre les versions.
Règle 7 : Documentez votre API
Documentez les fonctions publiques, les classes, les arguments, les valeurs de retour et les exceptions. Utilisez un style de docstring cohérent afin que les outils automatisés puissent générer une documentation API lisible.
Exemple :
def run_simulation(config_path, steps):
"""Run the simulation from a configuration file.
Args:
config_path: Path to the YAML configuration file.
steps: Number of time steps to run.
Returns:
Simulation results object with fields, metadata, and diagnostics.
Raises:
ValueError: If the configuration file is invalid.
"""
...
Règle 8 : Utiliser des outils de documentation automatisés
N’écrivez pas tout manuellement si les outils peuvent en générer une partie. Les outils de documentation automatisés réduisent le travail répétitif et gardent la documentation plus proche du code.
Les outils utiles comprennent :
- Sphinx pour les packages Python avec des API complexes.
- mkdocs pour les sites de documentation simples basés sur Markdown.
- Lisez les documents pour l’hébergement et les générations de documentation automatique.
Règle 9 : Rédiger des messages d’erreur exploitables
Les bons messages d’erreur indiquent aux utilisateurs ce qui n’allait pas, pourquoi cela s’est produit et comment y remédier.
# Bad
raise ValueError("Invalid input")
# Good
raise ValueError(
f"Input parameter 'temperature' must be between 0 and 3000 K. "
f"Received {temperature} K. Check your simulation config file."
)
Cela permet d’économiser du temps de débogage et de réduire les demandes d’assistance.
Règle 10 : Dites aux gens comment citer votre logiciel
Si vous souhaitez que votre logiciel de recherche soit crédité, fournissez des instructions de citation. Incluez un fichier DOI, BIBTEX ENTRY et CITATION.cff.
Si le logiciel n’a pas de publication dans un journal, utilisez Zenodo pour créer un DOI pour les versions. La soumission au Journal of Open Source Software peut également faciliter la citation des logiciels.
Modèles de documentation que vous pouvez utiliser aujourd’hui
L’arbre de décision de documentation
Avant de rédiger une documentation, posez trois questions :
- C’est pour qui ? Utilisateurs, développeurs, mainteneurs, réviseurs ou collaborateurs ?
- Que veulent-ils ? Exécuter le logiciel, le modifier, comprendre le modèle ou le citer ?
- Quel format répond au besoin ? Tutoriel, guide pratique, référence, explication, commentaire en ligne ou page d’API ?
Ces questions aident à prévenir une erreur courante : écrire un document surchargé pour chaque public.
Le format du fichier de citation
Le fichier CITATION.cff est un fichier lisible par machine et lisible par l’homme pour la citation logicielle. Il peut inclure :
- Nom et version du logiciel.
- Auteurs et affiliations.
- doi pour le logiciel.
- Informations Bibtex.
- URL du référentiel.
Lorsqu’il est associé à un Zenodo DOI, CITATION.cff devient un enregistrement de citation stable pour votre logiciel.
Exemple de modèle de citation.cff
cff-version: 1.2.0
message: "If you use this software, please cite it as below."
title: "Project Name"
version: "1.0.0"
doi: "10.5281/zenodo.xxxxxxx"
authors:
- family-names: "Surname"
given-names: "First Name"
affiliation: "Research Institution"
repository-code: "https://github.com/username/project-name"
license: "MIT"
Outils du métier
| Outil | But | le mieux pour |
|---|---|---|
| Sphinx | Génère de la documentation à partir de DocStrings et RestructuredText ou Markdown | Packages Python avec des API complexes |
| Mkdocs | Construit des sites de documentation basés sur Markdown | Projets légers nécessitant un site de documentation simple |
| Lire les docs | Hôtes et générations automatiques de documentation versionnée | Projets nécessitant un déploiement automatique de documentation |
| doxygen | Génère de la documentation pour les projets C, C++, Python et en langues mixtes | Projets avec des bases de code C++ ou mixtes scientifiques |
| zénodo | Mints Dois et archives Logiciels | Citation à long terme et reproductibilité |
erreurs courantes et comment les éviter
Erreur 1 : Traiter tout comme un lisez-moi
Un readme ne peut pas bien faire tous les travaux. Si vous combinez des didacticiels, des références, des explications, des détails de l’API et un dépannage dans un seul fichier, les utilisateurs ont du mal à trouver ce dont ils ont besoin.
Séparez la documentation par objectif à l’aide des quadrants Diátaxis.
Erreur 2 : Écrire des explications dans des tutoriels
Les didacticiels doivent être courts, pratiques et linéaires. Si un débutant doit comprendre le modèle mathématique avant d’utiliser le logiciel, placez cette explication sur une page séparée et faites un lien vers celui-ci.
Erreur 3 : la documentation ne contrôle pas les versions
Si vous modifiez un paramètre par défaut dans la version 2.0, les utilisateurs de la version 1.5 ont besoin de l’ancienne documentation. Les documents versionnés empêchent la confusion et rendent les versions plus anciennes plus utilisables.
Erreur 4 : En supposant que vous vous souviendrez de tout, en supposant que
Vous ne vous souvenez peut-être pas de vos décisions de conception six mois plus tard. Les pages de commentaires et d’explications servent de bloc-notes de laboratoire pour vos choix d’implémentation.
Erreur 5 : Oublier les instructions de citation
Les logiciels sans conseils de citation reçoivent souvent moins de crédit. Incluez un fichier DOI, BIBTEX et CITATION.cff afin que les utilisateurs sachent exactement comment citer votre travail.
Un workflow de documentation pratique
Vous pouvez mettre en œuvre la documentation par étapes. L’objectif n’est pas de tout écrire en même temps, mais de construire la structure tôt et de l’améliorer à mesure que le projet mûrit.
Phase 1 : avant d’écrire un code
- Créez un brouillon
CITATION.cff. - Rédigez un fichier skeleton readme avec le but du projet, l’espace réservé d’installation et la licence.
- Décidez si le public principal est celui des utilisateurs, des développeurs, des mainteneurs ou les trois.
Phase 2 : Pendant le développement
- Écrivez des commentaires comme vous codez, en particulier pour les choix algorithmiques.
- Ajoutez des docstrings pour chaque fonction publique et classe.
- Configurez tôt Sphinx ou MKDocs afin que la documentation soit construite avec le code.
- Ajoutez des exemples lorsque les fonctionnalités deviennent stables.
Phase 3 : Après le développement
- Rédigez un guide de démarrage rapide.
- Complétez le Lisez-moi avec les instructions d’installation, d’utilisation, de licence et de citation.
- Écrivez au moins un guide pratique pour le cas d’utilisation le plus courant.
- Créez ou mettez à jour le DOI via Zenodo, JOSS ou un autre itinéraire de publication approprié.
Liens internes et guides connexes
Pour les sujets connexes dans les flux de travail de simulation scientifique :
- Meilleures pratiques de documentation pour les packages Scientific Python – Structure d’outillage et de documentation spécifique à Python.
- Intégration continue pour les logiciels de recherche — CI/CD pour des tests et validations automatisés.
- lecture et compréhension de la documentation FIPY — modèles de documentation FIPY pratiques.
- Flows de recherche reproductibles : Docker et Conda : reproductibilité de l’environnement.
- Meilleures pratiques pour maintenir le code scientifique — Maintenance de projets à long terme.
Résumé et étapes suivantes
La documentation transforme le code d’un artefact expérimental fragile en un atout de recherche durable. Le cadre de Diátaxis donne une structure. Les dix règles simples donnent une liste de contrôle pratique. Les modèles et les outils fournissent un point de départ rapide.
Commencez par une petite étape : créez un fichier CITATION.cff et ajoutez des conseils de citation. Cela rend le logiciel plus facile à citer et à créditer.
Ajoutez ensuite un Lisez-moi avec des liens d’installation, de démarrage rapide, de licence et de documentation. Il s’agit du document le plus percutant pour la convivialité.
Ensuite, documentez l’API avec des doctrings cohérents et configurez Sphinx ou MKDocs. Cela aide les utilisateurs et les futurs mainteneurs à comprendre le fonctionnement du code.
Enfin, écrivez au moins un guide pratique pour le cas d’utilisation le plus courant. C’est souvent ce dont les collaborateurs ont réellement besoin.
Chaque documentation rend votre logiciel un peu plus près de la recherche reproductible.
Références et lectures complémentaires
- Lee, B. D. (2018). Dix règles simples pour documenter les logiciels scientifiques. biologie computationnelle PLOS, 14(12) : e1006561. doi : 10.1371/journal.pcbi.1006561
- Institut de développement durable des logiciels. Quelles sont les meilleures pratiques pour la documentation des logiciels de recherche ? source
- Procida, D. Diátaxis : une approche systématique de la création de documentation technique. Source
- Wilson, G., et al. (2014). Meilleures pratiques pour le calcul scientifique. biologie PLOS, 12(1) : e1001745. doi : 10.1371/journal.pbio.1001745
- Journal des logiciels open source. Source
- Lisez les docs. Source
Besoin d’aide pour structurer la documentation pour votre projet de simulation ?
Si votre équipe de recherche a besoin d’aide pour la mise en place de pipelines de documentation automatisée, la conception d’une structure de documentation conforme à Diátaxis ou l’intégration de la documentation dans les flux de travail CI/CD, nos experts en sciences informatiques peuvent vous aider.
Contactez-nous via notre Système de suivi des problèmes pour discuter des besoins en documentation de votre projet.