{"id":1268,"date":"2026-08-21T14:31:34","date_gmt":"2026-08-21T14:31:34","guid":{"rendered":"https:\/\/matforge.org\/?p=1268","raw":"https:\/\/matforge.org\/?p=1268"},"modified":"2026-08-21T14:31:34","modified_gmt":"2026-08-21T14:31:34","slug":"research-software-documentation-practical-guide-scientists","status":"publish","type":"post","link":"https:\/\/matforge.org\/fr\/research-software-documentation-practical-guide-scientists\/","title":{"rendered":"Documentation sur les logiciels de recherche : un guide pratique pour les scientifiques","raw":"Documentation sur les logiciels de recherche : un guide pratique pour les scientifiques"},"content":{"rendered":"<span class=\"span-reading-time rt-reading-time\" style=\"display: block;\"><span class=\"rt-label rt-prefix\">Reading Time: <\/span> <span class=\"rt-time\"> 9<\/span> <span class=\"rt-label rt-postfix\">minutes<\/span><\/span><p>Vous venez de terminer un pipeline de simulation. Vos r\u00e9sultats sont pr\u00eats \u00e0 \u00eatre publi\u00e9s. Votre code fonctionne. Alors pourquoi avez-vous encore besoin de le documenter ?<\/p>\n<p>Parce que sans documentation, votre logiciel est plus difficile \u00e0 citer, plus difficile \u00e0 reproduire et plus difficile \u00e0 entretenir. Les collaborateurs peuvent ne pas comprendre comment l&rsquo;ex\u00e9cuter. Les futurs \u00e9tudiants ne savent peut-\u00eatre pas quel fichier de configuration est important. M\u00eame si vous oubliez peut-\u00eatre les principales d\u00e9cisions de conception apr\u00e8s plusieurs mois.<\/p>\n<p>La documentation n&rsquo;est pas un compl\u00e9ment int\u00e9ressant pour les logiciels de recherche. C&rsquo;est le pont entre un outil de travail et un atout de recherche reproductible. Vous n&rsquo;avez pas besoin d&rsquo;\u00eatre un r\u00e9dacteur technique pour bien le faire. Vous avez besoin d&rsquo;une structure.<\/p>\n<h2>Points \u00e0 retenir cl\u00e9s<\/h2>\n<ul>\n<li>La documentation fait partie de la recherche reproductible. Le code sans documentation devient une bo\u00eete noire que seul son auteur d&rsquo;origine peut maintenir.<\/li>\n<li>Quatre types de documentation r\u00e9pondent \u00e0 quatre besoins d&rsquo;utilisateurs diff\u00e9rents&nbsp;: des didacticiels pour l&rsquo;apprentissage, des guides pratiques pour faire, des r\u00e9f\u00e9rences pour la description et des explications pour la compr\u00e9hension.<\/li>\n<li>Le cadre Di\u00e1taxis est un moyen pratique d&rsquo;organiser la documentation des logiciels de recherche.<\/li>\n<li>Les dix r\u00e8gles simples pour documenter les logiciels scientifiques fournissent une liste de contr\u00f4le utile pour r\u00e9diger une meilleure documentation.<\/li>\n<li>Des mod\u00e8les et des outils existent d\u00e9j\u00e0. Lisez-moi les structures, les fichiers <code>CITATION.cff<\/code>, Sphinx, MkDocs et Read the Docs rendent le processus plus efficace.<\/li>\n<\/ul>\n<h2>Pourquoi la documentation est importante<\/h2>\n<p>Les logiciels de recherche se situent entre la science et l&rsquo;ing\u00e9nierie. Contrairement aux \u00e9quipements de laboratoire traditionnels, les logiciels peuvent \u00eatre partag\u00e9s, modifi\u00e9s, r\u00e9utilis\u00e9s et cit\u00e9s par toute personne ayant le bon environnement. Mais ce potentiel signifie peu si personne ne comprend comment fonctionne le logiciel.<\/p>\n<p>Les enjeux sont pratiques :<\/p>\n<ul>\n<li>reproductibilit\u00e9. Sans documentation, d&rsquo;autres chercheurs ne peuvent pas v\u00e9rifier ou r\u00e9utiliser de mani\u00e8re fiable votre travail.<\/li>\n<li>Citation. Les logiciels qui manquent de conseils et d&rsquo;instructions d&rsquo;utilisation sont moins susceptibles de recevoir un cr\u00e9dit appropri\u00e9.<\/li>\n<li>Entretien. Lorsqu&rsquo;un chercheur quitte un laboratoire, le code non document\u00e9 devient souvent une dette technique pour la personne suivante.<\/li>\n<\/ul>\n<p>Une bonne documentation facilite l&rsquo;utilisation, l&rsquo;extension, la r\u00e9vision et la pr\u00e9servation des logiciels. Cela r\u00e9duit \u00e9galement le nombre de questions r\u00e9p\u00e9t\u00e9es des collaborateurs et des futurs utilisateurs.<\/p>\n<p>Ce guide vous donne un cadre et des mod\u00e8les pratiques pour documenter efficacement les logiciels de recherche.<\/p>\n<h2>Le cadre Di\u00e1taxis : quatre types de documentation<\/h2>\n<p>Si votre documentation se trouve actuellement dans un long fichier Lisez-moi, cela peut sembler d\u00e9sorganis\u00e9. Les didacticiels, les notes d&rsquo;installation, les d\u00e9tails de l&rsquo;API, la th\u00e9orie, les exemples et le d\u00e9pannage peuvent facilement se m\u00e9langer.<\/p>\n<p>Le cadre de Di\u00e1taxis r\u00e9sout ce probl\u00e8me en s\u00e9parant la documentation en quatre types distincts. Chaque type r\u00e9pond \u00e0 un besoin diff\u00e9rent de l&rsquo;utilisateur.<\/p>\n<h3>1. Tutoriels<\/h3>\n<p>Un didacticiel est orient\u00e9 vers l&rsquo;apprentissage. Il am\u00e8ne un d\u00e9butant \u00e0 un cheminement guid\u00e9 et l&rsquo;aide \u00e0 atteindre un r\u00e9sultat concret.<\/p>\n<p>Exemple&nbsp;: \u00ab\u00a0Configurez FIPY pour votre premi\u00e8re simulation de champ de phase.\u00a0\u00bb<\/p>\n<p>Un tutoriel R\u00e9ponses&nbsp;: Comment apprendre \u00e0 utiliser ce logiciel&nbsp;?<\/p>\n<h3>2. Guides pratiques<\/h3>\n<p>Un guide pratique est orient\u00e9 vers l&rsquo;action. Cela aide quelqu&rsquo;un \u00e0 accomplir une t\u00e2che sp\u00e9cifique apr\u00e8s avoir d\u00e9j\u00e0 compris les bases.<\/p>\n<p>Les exemples incluent :<\/p>\n<ul>\n<li>Comment ex\u00e9cuter une simulation de Monte Carlo avec Fipy.<\/li>\n<li>Comment r\u00e9soudre les erreurs de convergence.<\/li>\n<li>Comment exporter les r\u00e9sultats de la simulation au CSV.<\/li>\n<\/ul>\n<p>A Guide pratique R\u00e9ponses&nbsp;: Comment puis-je accomplir une t\u00e2che sp\u00e9cifique&nbsp;?<\/p>\n<h3>3. R\u00e9f\u00e9rence<\/h3>\n<p>La documentation de r\u00e9f\u00e9rence est orient\u00e9e vers l&rsquo;information. Il est factuel, neutre et complet. Il d\u00e9crit ce que le logiciel fournit sans enseignement ni persuasion.<\/p>\n<p>Les exemples incluent :<\/p>\n<ul>\n<li>Documentation de l&rsquo;API.<\/li>\n<li>signatures de fonctions.<\/li>\n<li>Sp\u00e9cifications des param\u00e8tres.<\/li>\n<li>D\u00e9finitions des classes.<\/li>\n<\/ul>\n<p>Documentation de r\u00e9f\u00e9rence R\u00e9ponses&nbsp;: \u00e0 quoi cela sert-il&nbsp;?<\/p>\n<h3>4. Explication<\/h3>\n<p>L&rsquo;explication est orient\u00e9e vers la compr\u00e9hension. Il fournit un contexte, un contexte, un raisonnement et une justification de la conception.<\/p>\n<p>Les exemples incluent :<\/p>\n<ul>\n<li>Pourquoi le solveur utilise un pas de temps implicite.<\/li>\n<li>Le mod\u00e8le math\u00e9matique derri\u00e8re la mise en \u0153uvre.<\/li>\n<li>Pourquoi une strat\u00e9gie de maillage a \u00e9t\u00e9 choisie plut\u00f4t qu&rsquo;une autre.<\/li>\n<\/ul>\n<p>R\u00e9ponses d&rsquo;explication : Pourquoi cela fonctionne-t-il de cette fa\u00e7on ?<\/p>\n<h2>Les dix r\u00e8gles simples pour documenter les logiciels de recherche<\/h2>\n<p>Les dix r\u00e8gles simples pour documenter les logiciels scientifiques constituent une liste de contr\u00f4le pratique pour la qualit\u00e9 de la documentation. Ils sont utiles car ils se concentrent sur les habitudes que les chercheurs peuvent appliquer sans cr\u00e9er un service de documentation complet.<\/p>\n<h3>R\u00e8gle&nbsp;1&nbsp;: \u00c9crivez des commentaires au fur et \u00e0 mesure de votre code<\/h3>\n<p>Les commentaires doivent expliquer les id\u00e9es et le raisonnement derri\u00e8re l&rsquo;algorithme, et non pas simplement r\u00e9p\u00e9ter ce que le code dit d\u00e9j\u00e0.<\/p>\n<pre><code class=\"language-python\"># Good: explains why this approach is used\n# Use implicit time stepping for stiff reaction terms to avoid\n# timestep restrictions that would make the simulation impractical.\nsolver = ImplicitTimeStepping(reaction_terms)\n\n# Bad: repeats the line without explaining intent\nsolver = ImplicitTimeStepping(reaction_terms)  # creates solver\n<\/code><\/pre>\n<h3>R\u00e8gle 2 : Inclure de nombreux exemples<\/h3>\n<p>Des exemples montrent aux utilisateurs comment le logiciel fonctionne dans la pratique. Fournissez des exemples ex\u00e9cutables qui illustrent le flux de travail principal.<\/p>\n<p>Si la documentation est trop encombr\u00e9e d&rsquo;exemples, d\u00e9placez-les dans un r\u00e9pertoire d\u00e9di\u00e9 <code>examples\/<\/code> et associez-les \u00e0 partir de la documentation principale.<\/p>\n<h3>R\u00e8gle&nbsp;3&nbsp;: Incluez un guide de d\u00e9marrage rapide<\/h3>\n<p>Un guide de d\u00e9marrage rapide devrait permettre \u00e0 quelqu&rsquo;un d&rsquo;utiliser le logiciel quelques minutes apr\u00e8s son t\u00e9l\u00e9chargement. Cela devrait inclure une installation, un exemple minimal et une sortie attendue.<\/p>\n<p>Sans un d\u00e9marrage rapide, de nombreux utilisateurs supposent que le logiciel est trop difficile \u00e0 utiliser et \u00e0 partir avant de le tester.<\/p>\n<h3>R\u00e8gle&nbsp;4&nbsp;: R\u00e9digez un fichier Lisez-moi<\/h3>\n<p>Supposons que le readme sera la seule documentation lue par de nombreux utilisateurs. Il devrait couvrir clairement l&rsquo;essentiel.<\/p>\n<p>Un README fort devrait inclure :<\/p>\n<ul>\n<li>Une br\u00e8ve description du projet.<\/li>\n<li>Instructions d&rsquo;installation et d\u00e9pendances.<\/li>\n<li>Un exemple de d\u00e9marrage rapide.<\/li>\n<li>Informations sur la licence.<\/li>\n<li>Instructions de citation.<\/li>\n<li>Un lien vers une documentation compl\u00e8te.<\/li>\n<\/ul>\n<p>Mod\u00e8le de lecture :<\/p>\n<pre><code class=\"language-markdown\"># Project Name\n\nShort description: one sentence explaining what the software does.\n\n## Installation\n\n1. Clone this repository.\n2. Run `pip install -e .` or your preferred install command.\n3. Verify the installation:\n\n```python\nimport mypackage\nprint(mypackage.__version__)\n```\n\n## Quickstart\n\n```python\nfrom mypackage import MySimulator\n\nsim = MySimulator(config=\"default.yaml\")\nresults = sim.run()\n```\n\n## Documentation\n\nFull documentation: [Read the Docs link]\n\n## Citation\n\nPlease cite this software using the CITATION.cff file.\n\n## License\n\nMIT License\n<\/code><\/pre>\n<h3>R\u00e8gle&nbsp;5&nbsp;: inclure une commande d&rsquo;aide pour les CLI<\/h3>\n<p>Si votre logiciel dispose d&rsquo;une interface de ligne de commande, incluez un indicateur clair <code>--help<\/code>. Il doit expliquer les commandes, les arguments requis, les param\u00e8tres optionnels et les exemples.<\/p>\n<p>Les outils Python tels que <code>argparse<\/code> rendent cela simple.<\/p>\n<h3>R\u00e8gle&nbsp;6&nbsp;: Contr\u00f4le de version de votre documentation<\/h3>\n<p>Conservez la documentation \u00e0 c\u00f4t\u00e9 du code dans le contr\u00f4le de version. Les utilisateurs de versions de logiciels plus anciennes ont besoin d&rsquo;un acc\u00e8s \u00e0 une documentation correspondant \u00e0 ces versions.<\/p>\n<p>Utilisez l&rsquo;h\u00e9bergement de documentation versionn\u00e9 lorsque cela est possible afin que les utilisateurs puissent basculer entre les versions.<\/p>\n<h3>R\u00e8gle&nbsp;7&nbsp;: Documentez votre API<\/h3>\n<p>Documentez les fonctions publiques, les classes, les arguments, les valeurs de retour et les exceptions. Utilisez un style de docstring coh\u00e9rent afin que les outils automatis\u00e9s puissent g\u00e9n\u00e9rer une documentation API lisible.<\/p>\n<p>Exemple&nbsp;:<\/p>\n<pre><code class=\"language-python\">def run_simulation(config_path, steps):\n    \"\"\"Run the simulation from a configuration file.\n\n    Args:\n        config_path: Path to the YAML configuration file.\n        steps: Number of time steps to run.\n\n    Returns:\n        Simulation results object with fields, metadata, and diagnostics.\n\n    Raises:\n        ValueError: If the configuration file is invalid.\n    \"\"\"\n    ...\n<\/code><\/pre>\n<h3>R\u00e8gle 8 : Utiliser des outils de documentation automatis\u00e9s<\/h3>\n<p>N&rsquo;\u00e9crivez pas tout manuellement si les outils peuvent en g\u00e9n\u00e9rer une partie. Les outils de documentation automatis\u00e9s r\u00e9duisent le travail r\u00e9p\u00e9titif et gardent la documentation plus proche du code.<\/p>\n<p>Les outils utiles comprennent :<\/p>\n<ul>\n<li>Sphinx pour les packages Python avec des API complexes.<\/li>\n<li>mkdocs pour les sites de documentation simples bas\u00e9s sur Markdown.<\/li>\n<li>Lisez les documents pour l&rsquo;h\u00e9bergement et les g\u00e9n\u00e9rations de documentation automatique.<\/li>\n<\/ul>\n<h3>R\u00e8gle 9 : R\u00e9diger des messages d&rsquo;erreur exploitables<\/h3>\n<p>Les bons messages d&rsquo;erreur indiquent aux utilisateurs ce qui n&rsquo;allait pas, pourquoi cela s&rsquo;est produit et comment y rem\u00e9dier.<\/p>\n<pre><code class=\"language-python\"># Bad\nraise ValueError(\"Invalid input\")\n\n# Good\nraise ValueError(\n    f\"Input parameter 'temperature' must be between 0 and 3000 K. \"\n    f\"Received {temperature} K. Check your simulation config file.\"\n)\n<\/code><\/pre>\n<p>Cela permet d&rsquo;\u00e9conomiser du temps de d\u00e9bogage et de r\u00e9duire les demandes d&rsquo;assistance.<\/p>\n<h3>R\u00e8gle&nbsp;10&nbsp;: Dites aux gens comment citer votre logiciel<\/h3>\n<p>Si vous souhaitez que votre logiciel de recherche soit cr\u00e9dit\u00e9, fournissez des instructions de citation. Incluez un fichier DOI, BIBTEX ENTRY et <code>CITATION.cff<\/code>.<\/p>\n<p>Si le logiciel n&rsquo;a pas de publication dans un journal, utilisez Zenodo pour cr\u00e9er un DOI pour les versions. La soumission au Journal of Open Source Software peut \u00e9galement faciliter la citation des logiciels.<\/p>\n<h2>Mod\u00e8les de documentation que vous pouvez utiliser aujourd&rsquo;hui<\/h2>\n<h3>L&rsquo;arbre de d\u00e9cision de documentation<\/h3>\n<p>Avant de r\u00e9diger une documentation, posez trois questions :<\/p>\n<ol>\n<li>C&rsquo;est pour qui ? Utilisateurs, d\u00e9veloppeurs, mainteneurs, r\u00e9viseurs ou collaborateurs&nbsp;?<\/li>\n<li>Que veulent-ils ? Ex\u00e9cuter le logiciel, le modifier, comprendre le mod\u00e8le ou le citer&nbsp;?<\/li>\n<li>Quel format r\u00e9pond au besoin ? Tutoriel, guide pratique, r\u00e9f\u00e9rence, explication, commentaire en ligne ou page d&rsquo;API&nbsp;?<\/li>\n<\/ol>\n<p>Ces questions aident \u00e0 pr\u00e9venir une erreur courante&nbsp;: \u00e9crire un document surcharg\u00e9 pour chaque public.<\/p>\n<h3>Le format du fichier de citation<\/h3>\n<p>Le fichier <code>CITATION.cff<\/code> est un fichier lisible par machine et lisible par l&rsquo;homme pour la citation logicielle. Il peut inclure :<\/p>\n<ul>\n<li>Nom et version du logiciel.<\/li>\n<li>Auteurs et affiliations.<\/li>\n<li>doi pour le logiciel.<\/li>\n<li>Informations Bibtex.<\/li>\n<li>URL du r\u00e9f\u00e9rentiel.<\/li>\n<\/ul>\n<p>Lorsqu&rsquo;il est associ\u00e9 \u00e0 un Zenodo DOI, <code>CITATION.cff<\/code> devient un enregistrement de citation stable pour votre logiciel.<\/p>\n<h3>Exemple de mod\u00e8le de citation.cff<\/h3>\n<pre><code class=\"language-yaml\">cff-version: 1.2.0\nmessage: \"If you use this software, please cite it as below.\"\ntitle: \"Project Name\"\nversion: \"1.0.0\"\ndoi: \"10.5281\/zenodo.xxxxxxx\"\nauthors:\n  - family-names: \"Surname\"\n    given-names: \"First Name\"\n    affiliation: \"Research Institution\"\nrepository-code: \"https:\/\/github.com\/username\/project-name\"\nlicense: \"MIT\"\n<\/code><\/pre>\n<h2>Outils du m\u00e9tier<\/h2>\n<table class=\"custom-table\">\n<tbody>\n<tr>\n<th>Outil<\/th>\n<th>But<\/th>\n<th>le mieux pour<\/th>\n<\/tr>\n<tr>\n<td>Sphinx<\/td>\n<td>G\u00e9n\u00e8re de la documentation \u00e0 partir de DocStrings et RestructuredText ou Markdown<\/td>\n<td>Packages Python avec des API complexes<\/td>\n<\/tr>\n<tr>\n<td>Mkdocs<\/td>\n<td>Construit des sites de documentation bas\u00e9s sur Markdown<\/td>\n<td>Projets l\u00e9gers n\u00e9cessitant un site de documentation simple<\/td>\n<\/tr>\n<tr>\n<td>Lire les docs<\/td>\n<td>H\u00f4tes et g\u00e9n\u00e9rations automatiques de documentation versionn\u00e9e<\/td>\n<td>Projets n\u00e9cessitant un d\u00e9ploiement automatique de documentation<\/td>\n<\/tr>\n<tr>\n<td>doxygen<\/td>\n<td>G\u00e9n\u00e8re de la documentation pour les projets C, C++, Python et en langues mixtes<\/td>\n<td>Projets avec des bases de code C++ ou mixtes scientifiques<\/td>\n<\/tr>\n<tr>\n<td>z\u00e9nodo<\/td>\n<td>Mints Dois et archives Logiciels<\/td>\n<td>Citation \u00e0 long terme et reproductibilit\u00e9<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>erreurs courantes et comment les \u00e9viter<\/h2>\n<h3>Erreur&nbsp;1&nbsp;: Traiter tout comme un lisez-moi<\/h3>\n<p>Un readme ne peut pas bien faire tous les travaux. Si vous combinez des didacticiels, des r\u00e9f\u00e9rences, des explications, des d\u00e9tails de l&rsquo;API et un d\u00e9pannage dans un seul fichier, les utilisateurs ont du mal \u00e0 trouver ce dont ils ont besoin.<\/p>\n<p>S\u00e9parez la documentation par objectif \u00e0 l&rsquo;aide des quadrants Di\u00e1taxis.<\/p>\n<h3>Erreur&nbsp;2&nbsp;: \u00c9crire des explications dans des tutoriels<\/h3>\n<p>Les didacticiels doivent \u00eatre courts, pratiques et lin\u00e9aires. Si un d\u00e9butant doit comprendre le mod\u00e8le math\u00e9matique avant d&rsquo;utiliser le logiciel, placez cette explication sur une page s\u00e9par\u00e9e et faites un lien vers celui-ci.<\/p>\n<h3>Erreur&nbsp;3&nbsp;: la documentation ne contr\u00f4le pas les versions<\/h3>\n<p>Si vous modifiez un param\u00e8tre par d\u00e9faut dans la version 2.0, les utilisateurs de la version&nbsp;1.5 ont besoin de l&rsquo;ancienne documentation. Les documents versionn\u00e9s emp\u00eachent la confusion et rendent les versions plus anciennes plus utilisables.<\/p>\n<h3>Erreur 4&nbsp;: En supposant que vous vous souviendrez de tout, en supposant que<\/h3>\n<p>Vous ne vous souvenez peut-\u00eatre pas de vos d\u00e9cisions de conception six mois plus tard. Les pages de commentaires et d&rsquo;explications servent de bloc-notes de laboratoire pour vos choix d&rsquo;impl\u00e9mentation.<\/p>\n<h3>Erreur&nbsp;5&nbsp;: Oublier les instructions de citation<\/h3>\n<p>Les logiciels sans conseils de citation re\u00e7oivent souvent moins de cr\u00e9dit. Incluez un fichier DOI, BIBTEX et <code>CITATION.cff<\/code> afin que les utilisateurs sachent exactement comment citer votre travail.<\/p>\n<h2>Un workflow de documentation pratique<\/h2>\n<p>Vous pouvez mettre en \u0153uvre la documentation par \u00e9tapes. L&rsquo;objectif n&rsquo;est pas de tout \u00e9crire en m\u00eame temps, mais de construire la structure t\u00f4t et de l&rsquo;am\u00e9liorer \u00e0 mesure que le projet m\u00fbrit.<\/p>\n<h3>Phase 1 : avant d&rsquo;\u00e9crire un code<\/h3>\n<ol>\n<li>Cr\u00e9ez un brouillon <code>CITATION.cff<\/code>.<\/li>\n<li>R\u00e9digez un fichier skeleton readme avec le but du projet, l&rsquo;espace r\u00e9serv\u00e9 d&rsquo;installation et la licence.<\/li>\n<li>D\u00e9cidez si le public principal est celui des utilisateurs, des d\u00e9veloppeurs, des mainteneurs ou les trois.<\/li>\n<\/ol>\n<h3>Phase 2 : Pendant le d\u00e9veloppement<\/h3>\n<ol>\n<li>\u00c9crivez des commentaires comme vous codez, en particulier pour les choix algorithmiques.<\/li>\n<li>Ajoutez des docstrings pour chaque fonction publique et classe.<\/li>\n<li>Configurez t\u00f4t Sphinx ou MKDocs afin que la documentation soit construite avec le code.<\/li>\n<li>Ajoutez des exemples lorsque les fonctionnalit\u00e9s deviennent stables.<\/li>\n<\/ol>\n<h3>Phase 3 : Apr\u00e8s le d\u00e9veloppement<\/h3>\n<ol>\n<li>R\u00e9digez un guide de d\u00e9marrage rapide.<\/li>\n<li>Compl\u00e9tez le Lisez-moi avec les instructions d&rsquo;installation, d&rsquo;utilisation, de licence et de citation.<\/li>\n<li>\u00c9crivez au moins un guide pratique pour le cas d&rsquo;utilisation le plus courant.<\/li>\n<li>Cr\u00e9ez ou mettez \u00e0 jour le DOI via Zenodo, JOSS ou un autre itin\u00e9raire de publication appropri\u00e9.<\/li>\n<\/ol>\n<h2>Liens internes et guides connexes<\/h2>\n<p>Pour les sujets connexes dans les flux de travail de simulation scientifique&nbsp;:<\/p>\n<ul>\n<li><a href=\"https:\/\/matforge.org\/documentation-best-practices-scientific-python-packages\/\">Meilleures pratiques de documentation pour les packages Scientific Python<\/a> &#8211; Structure d&rsquo;outillage et de documentation sp\u00e9cifique \u00e0 Python.<\/li>\n<li><a href=\"https:\/\/matforge.org\/continuous-integration-research-software-automated-testing-validation\/\">Int\u00e9gration continue pour les logiciels de recherche<\/a> \u2014 CI\/CD pour des tests et validations automatis\u00e9s.<\/li>\n<li><a href=\"https:\/\/matforge.org\/reading-and-understanding-fipy-documentation\/\">lecture et compr\u00e9hension de la documentation FIPY<\/a> \u2014 mod\u00e8les de documentation FIPY pratiques.<\/li>\n<li><a href=\"https:\/\/matforge.org\/reproducible-research-workflows-docker-and-conda-for-simulation-projects\/\">Flows de recherche reproductibles&nbsp;: Docker et Conda<\/a>&nbsp;: reproductibilit\u00e9 de l&rsquo;environnement.<\/li>\n<li><a href=\"https:\/\/matforge.org\/best-practices-for-maintaining-scientific-code\/\">Meilleures pratiques pour maintenir le code scientifique<\/a> \u2014 Maintenance de projets \u00e0 long terme.<\/li>\n<\/ul>\n<h2>R\u00e9sum\u00e9 et \u00e9tapes suivantes<\/h2>\n<p>La documentation transforme le code d&rsquo;un artefact exp\u00e9rimental fragile en un atout de recherche durable. Le cadre de Di\u00e1taxis donne une structure. Les dix r\u00e8gles simples donnent une liste de contr\u00f4le pratique. Les mod\u00e8les et les outils fournissent un point de d\u00e9part rapide.<\/p>\n<p>Commencez par une petite \u00e9tape&nbsp;: cr\u00e9ez un fichier <code>CITATION.cff<\/code> et ajoutez des conseils de citation. Cela rend le logiciel plus facile \u00e0 citer et \u00e0 cr\u00e9diter.<\/p>\n<p>Ajoutez ensuite un Lisez-moi avec des liens d&rsquo;installation, de d\u00e9marrage rapide, de licence et de documentation. Il s&rsquo;agit du document le plus percutant pour la convivialit\u00e9.<\/p>\n<p>Ensuite, documentez l&rsquo;API avec des doctrings coh\u00e9rents et configurez Sphinx ou MKDocs. Cela aide les utilisateurs et les futurs mainteneurs \u00e0 comprendre le fonctionnement du code.<\/p>\n<p>Enfin, \u00e9crivez au moins un guide pratique pour le cas d&rsquo;utilisation le plus courant. C&rsquo;est souvent ce dont les collaborateurs ont r\u00e9ellement besoin.<\/p>\n<p>Chaque documentation rend votre logiciel un peu plus pr\u00e8s de la recherche reproductible.<\/p>\n<h2>R\u00e9f\u00e9rences et lectures compl\u00e9mentaires<\/h2>\n<ul>\n<li>Lee, B.&nbsp;D. (2018). Dix r\u00e8gles simples pour documenter les logiciels scientifiques. <em>biologie computationnelle PLOS<\/em>, 14(12)&nbsp;: e1006561. <a href=\"https:\/\/doi.org\/10.1371\/journal.pcbi.1006561\">doi&nbsp;: 10.1371\/journal.pcbi.1006561<\/a><\/li>\n<li>Institut de d\u00e9veloppement durable des logiciels. Quelles sont les meilleures pratiques pour la documentation des logiciels de recherche&nbsp;? <a href=\"https:\/\/www.software.ac.uk\/blog\/what-are-best-practices-research-software-documentation\">source<\/a><\/li>\n<li>Procida, D. Di\u00e1taxis&nbsp;: une approche syst\u00e9matique de la cr\u00e9ation de documentation technique. <a href=\"https:\/\/diataxis.fr\/\">Source<\/a><\/li>\n<li>Wilson, G., et al. (2014). Meilleures pratiques pour le calcul scientifique. <em>biologie PLOS<\/em>, 12(1)&nbsp;: e1001745. <a href=\"https:\/\/doi.org\/10.1371\/journal.pbio.1001745\">doi&nbsp;: 10.1371\/journal.pbio.1001745<\/a><\/li>\n<li>Journal des logiciels open source. <a href=\"https:\/\/joss.theoj.org\/\">Source<\/a><\/li>\n<li>Lisez les docs. <a href=\"https:\/\/readthedocs.org\/\">Source<\/a><\/li>\n<\/ul>\n<h2>Besoin d&rsquo;aide pour structurer la documentation pour votre projet de simulation ?<\/h2>\n<p>Si votre \u00e9quipe de recherche a besoin d&rsquo;aide pour la mise en place de pipelines de documentation automatis\u00e9e, la conception d&rsquo;une structure de documentation conforme \u00e0 Di\u00e1taxis ou l&rsquo;int\u00e9gration de la documentation dans les flux de travail CI\/CD, nos experts en sciences informatiques peuvent vous aider.<\/p>\n<p>Contactez-nous via notre <a href=\"https:\/\/matforge.org\/category\/issue-tracking-tickets-technical-requests\/\">Syst\u00e8me de suivi des probl\u00e8mes<\/a> pour discuter des besoins en documentation de votre projet.<\/p>\n","protected":false,"raw":"<p>Vous venez de terminer un pipeline de simulation. Vos r\u00e9sultats sont pr\u00eats \u00e0 \u00eatre publi\u00e9s. Votre code fonctionne. Alors pourquoi avez-vous encore besoin de le documenter ?<\/p>\n<p>Parce que sans documentation, votre logiciel est plus difficile \u00e0 citer, plus difficile \u00e0 reproduire et plus difficile \u00e0 entretenir. Les collaborateurs peuvent ne pas comprendre comment l'ex\u00e9cuter. Les futurs \u00e9tudiants ne savent peut-\u00eatre pas quel fichier de configuration est important. M\u00eame si vous oubliez peut-\u00eatre les principales d\u00e9cisions de conception apr\u00e8s plusieurs mois.<\/p>\n<p>La documentation n'est pas un compl\u00e9ment int\u00e9ressant 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'\u00eatre un r\u00e9dacteur technique pour bien le faire. Vous avez besoin d'une structure.<\/p>\n<h2>Points \u00e0 retenir cl\u00e9s<\/h2>\n<ul>\n<li>La documentation fait partie de la recherche reproductible. Le code sans documentation devient une bo\u00eete noire que seul son auteur d'origine peut maintenir.<\/li>\n<li>Quatre types de documentation r\u00e9pondent \u00e0 quatre besoins d'utilisateurs diff\u00e9rents&nbsp;: des didacticiels pour l'apprentissage, des guides pratiques pour faire, des r\u00e9f\u00e9rences pour la description et des explications pour la compr\u00e9hension.<\/li>\n<li>Le cadre Di\u00e1taxis est un moyen pratique d'organiser la documentation des logiciels de recherche.<\/li>\n<li>Les dix r\u00e8gles simples pour documenter les logiciels scientifiques fournissent une liste de contr\u00f4le utile pour r\u00e9diger une meilleure documentation.<\/li>\n<li>Des mod\u00e8les et des outils existent d\u00e9j\u00e0. Lisez-moi les structures, les fichiers <code>CITATION.cff<\/code>, Sphinx, MkDocs et Read the Docs rendent le processus plus efficace.<\/li>\n<\/ul>\n<h2>Pourquoi la documentation est importante<\/h2>\n<p>Les logiciels de recherche se situent entre la science et l'ing\u00e9nierie. Contrairement aux \u00e9quipements de laboratoire traditionnels, les logiciels peuvent \u00eatre partag\u00e9s, modifi\u00e9s, r\u00e9utilis\u00e9s et cit\u00e9s par toute personne ayant le bon environnement. Mais ce potentiel signifie peu si personne ne comprend comment fonctionne le logiciel.<\/p>\n<p>Les enjeux sont pratiques :<\/p>\n<ul>\n<li>reproductibilit\u00e9. Sans documentation, d'autres chercheurs ne peuvent pas v\u00e9rifier ou r\u00e9utiliser de mani\u00e8re fiable votre travail.<\/li>\n<li>Citation. Les logiciels qui manquent de conseils et d'instructions d'utilisation sont moins susceptibles de recevoir un cr\u00e9dit appropri\u00e9.<\/li>\n<li>Entretien. Lorsqu'un chercheur quitte un laboratoire, le code non document\u00e9 devient souvent une dette technique pour la personne suivante.<\/li>\n<\/ul>\n<p>Une bonne documentation facilite l'utilisation, l'extension, la r\u00e9vision et la pr\u00e9servation des logiciels. Cela r\u00e9duit \u00e9galement le nombre de questions r\u00e9p\u00e9t\u00e9es des collaborateurs et des futurs utilisateurs.<\/p>\n<p>Ce guide vous donne un cadre et des mod\u00e8les pratiques pour documenter efficacement les logiciels de recherche.<\/p>\n<h2>Le cadre Di\u00e1taxis : quatre types de documentation<\/h2>\n<p>Si votre documentation se trouve actuellement dans un long fichier Lisez-moi, cela peut sembler d\u00e9sorganis\u00e9. Les didacticiels, les notes d'installation, les d\u00e9tails de l'API, la th\u00e9orie, les exemples et le d\u00e9pannage peuvent facilement se m\u00e9langer.<\/p>\n<p>Le cadre de Di\u00e1taxis r\u00e9sout ce probl\u00e8me en s\u00e9parant la documentation en quatre types distincts. Chaque type r\u00e9pond \u00e0 un besoin diff\u00e9rent de l'utilisateur.<\/p>\n<h3>1. Tutoriels<\/h3>\n<p>Un didacticiel est orient\u00e9 vers l'apprentissage. Il am\u00e8ne un d\u00e9butant \u00e0 un cheminement guid\u00e9 et l'aide \u00e0 atteindre un r\u00e9sultat concret.<\/p>\n<p>Exemple&nbsp;: \"Configurez FIPY pour votre premi\u00e8re simulation de champ de phase.\"<\/p>\n<p>Un tutoriel R\u00e9ponses&nbsp;: Comment apprendre \u00e0 utiliser ce logiciel&nbsp;?<\/p>\n<h3>2. Guides pratiques<\/h3>\n<p>Un guide pratique est orient\u00e9 vers l'action. Cela aide quelqu'un \u00e0 accomplir une t\u00e2che sp\u00e9cifique apr\u00e8s avoir d\u00e9j\u00e0 compris les bases.<\/p>\n<p>Les exemples incluent :<\/p>\n<ul>\n<li>Comment ex\u00e9cuter une simulation de Monte Carlo avec Fipy.<\/li>\n<li>Comment r\u00e9soudre les erreurs de convergence.<\/li>\n<li>Comment exporter les r\u00e9sultats de la simulation au CSV.<\/li>\n<\/ul>\n<p>A Guide pratique R\u00e9ponses&nbsp;: Comment puis-je accomplir une t\u00e2che sp\u00e9cifique&nbsp;?<\/p>\n<h3>3. R\u00e9f\u00e9rence<\/h3>\n<p>La documentation de r\u00e9f\u00e9rence est orient\u00e9e vers l'information. Il est factuel, neutre et complet. Il d\u00e9crit ce que le logiciel fournit sans enseignement ni persuasion.<\/p>\n<p>Les exemples incluent :<\/p>\n<ul>\n<li>Documentation de l'API.<\/li>\n<li>signatures de fonctions.<\/li>\n<li>Sp\u00e9cifications des param\u00e8tres.<\/li>\n<li>D\u00e9finitions des classes.<\/li>\n<\/ul>\n<p>Documentation de r\u00e9f\u00e9rence R\u00e9ponses&nbsp;: \u00e0 quoi cela sert-il&nbsp;?<\/p>\n<h3>4. Explication<\/h3>\n<p>L'explication est orient\u00e9e vers la compr\u00e9hension. Il fournit un contexte, un contexte, un raisonnement et une justification de la conception.<\/p>\n<p>Les exemples incluent :<\/p>\n<ul>\n<li>Pourquoi le solveur utilise un pas de temps implicite.<\/li>\n<li>Le mod\u00e8le math\u00e9matique derri\u00e8re la mise en \u0153uvre.<\/li>\n<li>Pourquoi une strat\u00e9gie de maillage a \u00e9t\u00e9 choisie plut\u00f4t qu'une autre.<\/li>\n<\/ul>\n<p>R\u00e9ponses d'explication : Pourquoi cela fonctionne-t-il de cette fa\u00e7on ?<\/p>\n<h2>Les dix r\u00e8gles simples pour documenter les logiciels de recherche<\/h2>\n<p>Les dix r\u00e8gles simples pour documenter les logiciels scientifiques constituent une liste de contr\u00f4le pratique pour la qualit\u00e9 de la documentation. Ils sont utiles car ils se concentrent sur les habitudes que les chercheurs peuvent appliquer sans cr\u00e9er un service de documentation complet.<\/p>\n<h3>R\u00e8gle&nbsp;1&nbsp;: \u00c9crivez des commentaires au fur et \u00e0 mesure de votre code<\/h3>\n<p>Les commentaires doivent expliquer les id\u00e9es et le raisonnement derri\u00e8re l'algorithme, et non pas simplement r\u00e9p\u00e9ter ce que le code dit d\u00e9j\u00e0.<\/p>\n<pre><code class=\"language-python\"># Good: explains why this approach is used\n# Use implicit time stepping for stiff reaction terms to avoid\n# timestep restrictions that would make the simulation impractical.\nsolver = ImplicitTimeStepping(reaction_terms)\n\n# Bad: repeats the line without explaining intent\nsolver = ImplicitTimeStepping(reaction_terms)  # creates solver\n<\/code><\/pre>\n<h3>R\u00e8gle 2 : Inclure de nombreux exemples<\/h3>\n<p>Des exemples montrent aux utilisateurs comment le logiciel fonctionne dans la pratique. Fournissez des exemples ex\u00e9cutables qui illustrent le flux de travail principal.<\/p>\n<p>Si la documentation est trop encombr\u00e9e d'exemples, d\u00e9placez-les dans un r\u00e9pertoire d\u00e9di\u00e9 <code>examples\/<\/code> et associez-les \u00e0 partir de la documentation principale.<\/p>\n<h3>R\u00e8gle&nbsp;3&nbsp;: Incluez un guide de d\u00e9marrage rapide<\/h3>\n<p>Un guide de d\u00e9marrage rapide devrait permettre \u00e0 quelqu'un d'utiliser le logiciel quelques minutes apr\u00e8s son t\u00e9l\u00e9chargement. Cela devrait inclure une installation, un exemple minimal et une sortie attendue.<\/p>\n<p>Sans un d\u00e9marrage rapide, de nombreux utilisateurs supposent que le logiciel est trop difficile \u00e0 utiliser et \u00e0 partir avant de le tester.<\/p>\n<h3>R\u00e8gle&nbsp;4&nbsp;: R\u00e9digez un fichier Lisez-moi<\/h3>\n<p>Supposons que le readme sera la seule documentation lue par de nombreux utilisateurs. Il devrait couvrir clairement l'essentiel.<\/p>\n<p>Un README fort devrait inclure :<\/p>\n<ul>\n<li>Une br\u00e8ve description du projet.<\/li>\n<li>Instructions d'installation et d\u00e9pendances.<\/li>\n<li>Un exemple de d\u00e9marrage rapide.<\/li>\n<li>Informations sur la licence.<\/li>\n<li>Instructions de citation.<\/li>\n<li>Un lien vers une documentation compl\u00e8te.<\/li>\n<\/ul>\n<p>Mod\u00e8le de lecture :<\/p>\n<pre><code class=\"language-markdown\"># Project Name\n\nShort description: one sentence explaining what the software does.\n\n## Installation\n\n1. Clone this repository.\n2. Run `pip install -e .` or your preferred install command.\n3. Verify the installation:\n\n```python\nimport mypackage\nprint(mypackage.__version__)\n```\n\n## Quickstart\n\n```python\nfrom mypackage import MySimulator\n\nsim = MySimulator(config=\"default.yaml\")\nresults = sim.run()\n```\n\n## Documentation\n\nFull documentation: [Read the Docs link]\n\n## Citation\n\nPlease cite this software using the CITATION.cff file.\n\n## License\n\nMIT License\n<\/code><\/pre>\n<h3>R\u00e8gle&nbsp;5&nbsp;: inclure une commande d'aide pour les CLI<\/h3>\n<p>Si votre logiciel dispose d'une interface de ligne de commande, incluez un indicateur clair <code>--help<\/code>. Il doit expliquer les commandes, les arguments requis, les param\u00e8tres optionnels et les exemples.<\/p>\n<p>Les outils Python tels que <code>argparse<\/code> rendent cela simple.<\/p>\n<h3>R\u00e8gle&nbsp;6&nbsp;: Contr\u00f4le de version de votre documentation<\/h3>\n<p>Conservez la documentation \u00e0 c\u00f4t\u00e9 du code dans le contr\u00f4le de version. Les utilisateurs de versions de logiciels plus anciennes ont besoin d'un acc\u00e8s \u00e0 une documentation correspondant \u00e0 ces versions.<\/p>\n<p>Utilisez l'h\u00e9bergement de documentation versionn\u00e9 lorsque cela est possible afin que les utilisateurs puissent basculer entre les versions.<\/p>\n<h3>R\u00e8gle&nbsp;7&nbsp;: Documentez votre API<\/h3>\n<p>Documentez les fonctions publiques, les classes, les arguments, les valeurs de retour et les exceptions. Utilisez un style de docstring coh\u00e9rent afin que les outils automatis\u00e9s puissent g\u00e9n\u00e9rer une documentation API lisible.<\/p>\n<p>Exemple&nbsp;:<\/p>\n<pre><code class=\"language-python\">def run_simulation(config_path, steps):\n    \"\"\"Run the simulation from a configuration file.\n\n    Args:\n        config_path: Path to the YAML configuration file.\n        steps: Number of time steps to run.\n\n    Returns:\n        Simulation results object with fields, metadata, and diagnostics.\n\n    Raises:\n        ValueError: If the configuration file is invalid.\n    \"\"\"\n    ...\n<\/code><\/pre>\n<h3>R\u00e8gle 8 : Utiliser des outils de documentation automatis\u00e9s<\/h3>\n<p>N'\u00e9crivez pas tout manuellement si les outils peuvent en g\u00e9n\u00e9rer une partie. Les outils de documentation automatis\u00e9s r\u00e9duisent le travail r\u00e9p\u00e9titif et gardent la documentation plus proche du code.<\/p>\n<p>Les outils utiles comprennent :<\/p>\n<ul>\n<li>Sphinx pour les packages Python avec des API complexes.<\/li>\n<li>mkdocs pour les sites de documentation simples bas\u00e9s sur Markdown.<\/li>\n<li>Lisez les documents pour l'h\u00e9bergement et les g\u00e9n\u00e9rations de documentation automatique.<\/li>\n<\/ul>\n<h3>R\u00e8gle 9 : R\u00e9diger des messages d'erreur exploitables<\/h3>\n<p>Les bons messages d'erreur indiquent aux utilisateurs ce qui n'allait pas, pourquoi cela s'est produit et comment y rem\u00e9dier.<\/p>\n<pre><code class=\"language-python\"># Bad\nraise ValueError(\"Invalid input\")\n\n# Good\nraise ValueError(\n    f\"Input parameter 'temperature' must be between 0 and 3000 K. \"\n    f\"Received {temperature} K. Check your simulation config file.\"\n)\n<\/code><\/pre>\n<p>Cela permet d'\u00e9conomiser du temps de d\u00e9bogage et de r\u00e9duire les demandes d'assistance.<\/p>\n<h3>R\u00e8gle&nbsp;10&nbsp;: Dites aux gens comment citer votre logiciel<\/h3>\n<p>Si vous souhaitez que votre logiciel de recherche soit cr\u00e9dit\u00e9, fournissez des instructions de citation. Incluez un fichier DOI, BIBTEX ENTRY et <code>CITATION.cff<\/code>.<\/p>\n<p>Si le logiciel n'a pas de publication dans un journal, utilisez Zenodo pour cr\u00e9er un DOI pour les versions. La soumission au Journal of Open Source Software peut \u00e9galement faciliter la citation des logiciels.<\/p>\n<h2>Mod\u00e8les de documentation que vous pouvez utiliser aujourd'hui<\/h2>\n<h3>L'arbre de d\u00e9cision de documentation<\/h3>\n<p>Avant de r\u00e9diger une documentation, posez trois questions :<\/p>\n<ol>\n<li>C'est pour qui ? Utilisateurs, d\u00e9veloppeurs, mainteneurs, r\u00e9viseurs ou collaborateurs&nbsp;?<\/li>\n<li>Que veulent-ils ? Ex\u00e9cuter le logiciel, le modifier, comprendre le mod\u00e8le ou le citer&nbsp;?<\/li>\n<li>Quel format r\u00e9pond au besoin ? Tutoriel, guide pratique, r\u00e9f\u00e9rence, explication, commentaire en ligne ou page d'API&nbsp;?<\/li>\n<\/ol>\n<p>Ces questions aident \u00e0 pr\u00e9venir une erreur courante&nbsp;: \u00e9crire un document surcharg\u00e9 pour chaque public.<\/p>\n<h3>Le format du fichier de citation<\/h3>\n<p>Le fichier <code>CITATION.cff<\/code> est un fichier lisible par machine et lisible par l'homme pour la citation logicielle. Il peut inclure :<\/p>\n<ul>\n<li>Nom et version du logiciel.<\/li>\n<li>Auteurs et affiliations.<\/li>\n<li>doi pour le logiciel.<\/li>\n<li>Informations Bibtex.<\/li>\n<li>URL du r\u00e9f\u00e9rentiel.<\/li>\n<\/ul>\n<p>Lorsqu'il est associ\u00e9 \u00e0 un Zenodo DOI, <code>CITATION.cff<\/code> devient un enregistrement de citation stable pour votre logiciel.<\/p>\n<h3>Exemple de mod\u00e8le de citation.cff<\/h3>\n<pre><code class=\"language-yaml\">cff-version: 1.2.0\nmessage: \"If you use this software, please cite it as below.\"\ntitle: \"Project Name\"\nversion: \"1.0.0\"\ndoi: \"10.5281\/zenodo.xxxxxxx\"\nauthors:\n  - family-names: \"Surname\"\n    given-names: \"First Name\"\n    affiliation: \"Research Institution\"\nrepository-code: \"https:\/\/github.com\/username\/project-name\"\nlicense: \"MIT\"\n<\/code><\/pre>\n<h2>Outils du m\u00e9tier<\/h2>\n<table class=\"custom-table\">\n<tbody><tr>\n<th>Outil<\/th>\n<th>But<\/th>\n<th>le mieux pour<\/th>\n<\/tr>\n<tr>\n<td>Sphinx<\/td>\n<td>G\u00e9n\u00e8re de la documentation \u00e0 partir de DocStrings et RestructuredText ou Markdown<\/td>\n<td>Packages Python avec des API complexes<\/td>\n<\/tr>\n<tr>\n<td>Mkdocs<\/td>\n<td>Construit des sites de documentation bas\u00e9s sur Markdown<\/td>\n<td>Projets l\u00e9gers n\u00e9cessitant un site de documentation simple<\/td>\n<\/tr>\n<tr>\n<td>Lire les docs<\/td>\n<td>H\u00f4tes et g\u00e9n\u00e9rations automatiques de documentation versionn\u00e9e<\/td>\n<td>Projets n\u00e9cessitant un d\u00e9ploiement automatique de documentation<\/td>\n<\/tr>\n<tr>\n<td>doxygen<\/td>\n<td>G\u00e9n\u00e8re de la documentation pour les projets C, C++, Python et en langues mixtes<\/td>\n<td>Projets avec des bases de code C++ ou mixtes scientifiques<\/td>\n<\/tr>\n<tr>\n<td>z\u00e9nodo<\/td>\n<td>Mints Dois et archives Logiciels<\/td>\n<td>Citation \u00e0 long terme et reproductibilit\u00e9<\/td>\n<\/tr>\n<\/tbody><\/table>\n<h2>erreurs courantes et comment les \u00e9viter<\/h2>\n<h3>Erreur&nbsp;1&nbsp;: Traiter tout comme un lisez-moi<\/h3>\n<p>Un readme ne peut pas bien faire tous les travaux. Si vous combinez des didacticiels, des r\u00e9f\u00e9rences, des explications, des d\u00e9tails de l'API et un d\u00e9pannage dans un seul fichier, les utilisateurs ont du mal \u00e0 trouver ce dont ils ont besoin.<\/p>\n<p>S\u00e9parez la documentation par objectif \u00e0 l'aide des quadrants Di\u00e1taxis.<\/p>\n<h3>Erreur&nbsp;2&nbsp;: \u00c9crire des explications dans des tutoriels<\/h3>\n<p>Les didacticiels doivent \u00eatre courts, pratiques et lin\u00e9aires. Si un d\u00e9butant doit comprendre le mod\u00e8le math\u00e9matique avant d'utiliser le logiciel, placez cette explication sur une page s\u00e9par\u00e9e et faites un lien vers celui-ci.<\/p>\n<h3>Erreur&nbsp;3&nbsp;: la documentation ne contr\u00f4le pas les versions<\/h3>\n<p>Si vous modifiez un param\u00e8tre par d\u00e9faut dans la version 2.0, les utilisateurs de la version&nbsp;1.5 ont besoin de l'ancienne documentation. Les documents versionn\u00e9s emp\u00eachent la confusion et rendent les versions plus anciennes plus utilisables.<\/p>\n<h3>Erreur 4&nbsp;: En supposant que vous vous souviendrez de tout, en supposant que<\/h3>\n<p>Vous ne vous souvenez peut-\u00eatre pas de vos d\u00e9cisions de conception six mois plus tard. Les pages de commentaires et d'explications servent de bloc-notes de laboratoire pour vos choix d'impl\u00e9mentation.<\/p>\n<h3>Erreur&nbsp;5&nbsp;: Oublier les instructions de citation<\/h3>\n<p>Les logiciels sans conseils de citation re\u00e7oivent souvent moins de cr\u00e9dit. Incluez un fichier DOI, BIBTEX et <code>CITATION.cff<\/code> afin que les utilisateurs sachent exactement comment citer votre travail.<\/p>\n<h2>Un workflow de documentation pratique<\/h2>\n<p>Vous pouvez mettre en \u0153uvre la documentation par \u00e9tapes. L'objectif n'est pas de tout \u00e9crire en m\u00eame temps, mais de construire la structure t\u00f4t et de l'am\u00e9liorer \u00e0 mesure que le projet m\u00fbrit.<\/p>\n<h3>Phase 1 : avant d'\u00e9crire un code<\/h3>\n<ol>\n<li>Cr\u00e9ez un brouillon <code>CITATION.cff<\/code>.<\/li>\n<li>R\u00e9digez un fichier skeleton readme avec le but du projet, l'espace r\u00e9serv\u00e9 d'installation et la licence.<\/li>\n<li>D\u00e9cidez si le public principal est celui des utilisateurs, des d\u00e9veloppeurs, des mainteneurs ou les trois.<\/li>\n<\/ol>\n<h3>Phase 2 : Pendant le d\u00e9veloppement<\/h3>\n<ol>\n<li>\u00c9crivez des commentaires comme vous codez, en particulier pour les choix algorithmiques.<\/li>\n<li>Ajoutez des docstrings pour chaque fonction publique et classe.<\/li>\n<li>Configurez t\u00f4t Sphinx ou MKDocs afin que la documentation soit construite avec le code.<\/li>\n<li>Ajoutez des exemples lorsque les fonctionnalit\u00e9s deviennent stables.<\/li>\n<\/ol>\n<h3>Phase 3 : Apr\u00e8s le d\u00e9veloppement<\/h3>\n<ol>\n<li>R\u00e9digez un guide de d\u00e9marrage rapide.<\/li>\n<li>Compl\u00e9tez le Lisez-moi avec les instructions d'installation, d'utilisation, de licence et de citation.<\/li>\n<li>\u00c9crivez au moins un guide pratique pour le cas d'utilisation le plus courant.<\/li>\n<li>Cr\u00e9ez ou mettez \u00e0 jour le DOI via Zenodo, JOSS ou un autre itin\u00e9raire de publication appropri\u00e9.<\/li>\n<\/ol>\n<h2>Liens internes et guides connexes<\/h2>\n<p>Pour les sujets connexes dans les flux de travail de simulation scientifique&nbsp;:<\/p>\n<ul>\n<li><a href=\"https:\/\/matforge.org\/documentation-best-practices-scientific-python-packages\/\">Meilleures pratiques de documentation pour les packages Scientific Python<\/a> - Structure d'outillage et de documentation sp\u00e9cifique \u00e0 Python.<\/li>\n<li><a href=\"https:\/\/matforge.org\/continuous-integration-research-software-automated-testing-validation\/\">Int\u00e9gration continue pour les logiciels de recherche<\/a> \u2014 CI\/CD pour des tests et validations automatis\u00e9s.<\/li>\n<li><a href=\"https:\/\/matforge.org\/reading-and-understanding-fipy-documentation\/\">lecture et compr\u00e9hension de la documentation FIPY<\/a> \u2014 mod\u00e8les de documentation FIPY pratiques.<\/li>\n<li><a href=\"https:\/\/matforge.org\/reproducible-research-workflows-docker-and-conda-for-simulation-projects\/\">Flows de recherche reproductibles&nbsp;: Docker et Conda<\/a>&nbsp;: reproductibilit\u00e9 de l'environnement.<\/li>\n<li><a href=\"https:\/\/matforge.org\/best-practices-for-maintaining-scientific-code\/\">Meilleures pratiques pour maintenir le code scientifique<\/a> \u2014 Maintenance de projets \u00e0 long terme.<\/li>\n<\/ul>\n<h2>R\u00e9sum\u00e9 et \u00e9tapes suivantes<\/h2>\n<p>La documentation transforme le code d'un artefact exp\u00e9rimental fragile en un atout de recherche durable. Le cadre de Di\u00e1taxis donne une structure. Les dix r\u00e8gles simples donnent une liste de contr\u00f4le pratique. Les mod\u00e8les et les outils fournissent un point de d\u00e9part rapide.<\/p>\n<p>Commencez par une petite \u00e9tape&nbsp;: cr\u00e9ez un fichier <code>CITATION.cff<\/code> et ajoutez des conseils de citation. Cela rend le logiciel plus facile \u00e0 citer et \u00e0 cr\u00e9diter.<\/p>\n<p>Ajoutez ensuite un Lisez-moi avec des liens d'installation, de d\u00e9marrage rapide, de licence et de documentation. Il s'agit du document le plus percutant pour la convivialit\u00e9.<\/p>\n<p>Ensuite, documentez l'API avec des doctrings coh\u00e9rents et configurez Sphinx ou MKDocs. Cela aide les utilisateurs et les futurs mainteneurs \u00e0 comprendre le fonctionnement du code.<\/p>\n<p>Enfin, \u00e9crivez au moins un guide pratique pour le cas d'utilisation le plus courant. C'est souvent ce dont les collaborateurs ont r\u00e9ellement besoin.<\/p>\n<p>Chaque documentation rend votre logiciel un peu plus pr\u00e8s de la recherche reproductible.<\/p>\n<h2>R\u00e9f\u00e9rences et lectures compl\u00e9mentaires<\/h2>\n<ul>\n<li>Lee, B.&nbsp;D. (2018). Dix r\u00e8gles simples pour documenter les logiciels scientifiques. <em>biologie computationnelle PLOS<\/em>, 14(12)&nbsp;: e1006561. <a href=\"https:\/\/doi.org\/10.1371\/journal.pcbi.1006561\">doi&nbsp;: 10.1371\/journal.pcbi.1006561<\/a><\/li>\n<li>Institut de d\u00e9veloppement durable des logiciels. Quelles sont les meilleures pratiques pour la documentation des logiciels de recherche&nbsp;? <a href=\"https:\/\/www.software.ac.uk\/blog\/what-are-best-practices-research-software-documentation\">source<\/a><\/li>\n<li>Procida, D. Di\u00e1taxis&nbsp;: une approche syst\u00e9matique de la cr\u00e9ation de documentation technique. <a href=\"https:\/\/diataxis.fr\/\">Source<\/a><\/li>\n<li>Wilson, G., et al. (2014). Meilleures pratiques pour le calcul scientifique. <em>biologie PLOS<\/em>, 12(1)&nbsp;: e1001745. <a href=\"https:\/\/doi.org\/10.1371\/journal.pbio.1001745\">doi&nbsp;: 10.1371\/journal.pbio.1001745<\/a><\/li>\n<li>Journal des logiciels open source. <a href=\"https:\/\/joss.theoj.org\/\">Source<\/a><\/li>\n<li>Lisez les docs. <a href=\"https:\/\/readthedocs.org\/\">Source<\/a><\/li>\n<\/ul>\n<h2>Besoin d'aide pour structurer la documentation pour votre projet de simulation ?<\/h2>\n<p>Si votre \u00e9quipe de recherche a besoin d'aide pour la mise en place de pipelines de documentation automatis\u00e9e, la conception d'une structure de documentation conforme \u00e0 Di\u00e1taxis ou l'int\u00e9gration de la documentation dans les flux de travail CI\/CD, nos experts en sciences informatiques peuvent vous aider.<\/p>\n<p>Contactez-nous via notre <a href=\"https:\/\/matforge.org\/category\/issue-tracking-tickets-technical-requests\/\">Syst\u00e8me de suivi des probl\u00e8mes<\/a> pour discuter des besoins en documentation de votre projet.<\/p>\n"},"excerpt":{"rendered":"<p><span class=\"span-reading-time rt-reading-time\" style=\"display: block;\"><span class=\"rt-label rt-prefix\">Reading Time: <\/span> <span class=\"rt-time\"> 9<\/span> <span class=\"rt-label rt-postfix\">minutes<\/span><\/span>Apprenez \u00e0 documenter les logiciels de recherche avec des mod\u00e8les pratiques, le cadre Di\u00e1taxis et les strat\u00e9gies \u00e9prouv\u00e9es des directives du Software Sustainability Institute et du PLOS.<\/p>\n","protected":false,"raw":"Apprenez \u00e0 documenter les logiciels de recherche avec des mod\u00e8les pratiques, le cadre Di\u00e1taxis et les strat\u00e9gies \u00e9prouv\u00e9es des directives du Software Sustainability Institute et du PLOS."},"author":4,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_locale":"fr_FR","_original_post":"https:\/\/matforge.org\/?p=342","iawp_total_views":1,"footnotes":""},"categories":[3],"tags":[],"class_list":["post-1268","post","type-post","status-publish","format-standard","hentry","category-issue-tracking-tickets-technical-requests","fr-FR"],"yoast_head":"<!-- This site is optimized with the Yoast SEO plugin v28.3 - https:\/\/yoast.com\/product\/yoast-seo-wordpress\/ -->\n<title>Guide de documentation des logiciels de recherche<\/title>\n<meta name=\"description\" content=\"Apprenez \u00e0 documenter les logiciels de recherche avec Di\u00e1taxis, Lisez-moi des mod\u00e8les, Citation.cff, Sphinx, MKDocs, lisez les documents et les r\u00e8gles pratiques.\" \/>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/matforge.org\/fr\/research-software-documentation-practical-guide-scientists\/\" \/>\n<meta property=\"og:locale\" content=\"fr_FR\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Guide de documentation des logiciels de recherche\" \/>\n<meta property=\"og:description\" content=\"Apprenez \u00e0 documenter les logiciels de recherche avec Di\u00e1taxis, Lisez-moi des mod\u00e8les, Citation.cff, Sphinx, MKDocs, lisez les documents et les r\u00e8gles pratiques.\" \/>\n<meta property=\"og:url\" content=\"https:\/\/matforge.org\/fr\/research-software-documentation-practical-guide-scientists\/\" \/>\n<meta property=\"og:site_name\" content=\"matforge.org\" \/>\n<meta property=\"article:published_time\" content=\"2026-08-21T14:31:34+00:00\" \/>\n<meta name=\"author\" content=\"Priya Nair\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"\u00c9crit par\" \/>\n\t<meta name=\"twitter:data1\" content=\"Priya Nair\" \/>\n\t<meta name=\"twitter:label2\" content=\"Dur\u00e9e de lecture estim\u00e9e\" \/>\n\t<meta name=\"twitter:data2\" content=\"14 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\\\/\\\/schema.org\",\"@graph\":[{\"@type\":\"Article\",\"@id\":\"https:\\\/\\\/matforge.org\\\/fr\\\/research-software-documentation-practical-guide-scientists\\\/#article\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/matforge.org\\\/fr\\\/research-software-documentation-practical-guide-scientists\\\/\"},\"author\":{\"name\":\"Priya Nair\",\"@id\":\"https:\\\/\\\/matforge.org\\\/#\\\/schema\\\/person\\\/2effd7bc155a5e6357f31dac970c5795\"},\"headline\":\"Documentation sur les logiciels de recherche : un guide pratique pour les scientifiques\",\"datePublished\":\"2026-08-21T14:31:34+00:00\",\"mainEntityOfPage\":{\"@id\":\"https:\\\/\\\/matforge.org\\\/fr\\\/research-software-documentation-practical-guide-scientists\\\/\"},\"wordCount\":2623,\"commentCount\":0,\"articleSection\":[\"Suivi des probl\u00e8mes, billets &amp; Demandes techniques\"],\"inLanguage\":\"fr-FR\",\"potentialAction\":[{\"@type\":\"CommentAction\",\"name\":\"Comment\",\"target\":[\"https:\\\/\\\/matforge.org\\\/fr\\\/research-software-documentation-practical-guide-scientists\\\/#respond\"]}]},{\"@type\":\"WebPage\",\"@id\":\"https:\\\/\\\/matforge.org\\\/fr\\\/research-software-documentation-practical-guide-scientists\\\/\",\"url\":\"https:\\\/\\\/matforge.org\\\/fr\\\/research-software-documentation-practical-guide-scientists\\\/\",\"name\":\"Guide de documentation des logiciels de recherche\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/matforge.org\\\/#website\"},\"datePublished\":\"2026-08-21T14:31:34+00:00\",\"author\":{\"@id\":\"https:\\\/\\\/matforge.org\\\/#\\\/schema\\\/person\\\/2effd7bc155a5e6357f31dac970c5795\"},\"description\":\"Apprenez \u00e0 documenter les logiciels de recherche avec Di\u00e1taxis, Lisez-moi des mod\u00e8les, Citation.cff, Sphinx, MKDocs, lisez les documents et les r\u00e8gles pratiques.\",\"breadcrumb\":{\"@id\":\"https:\\\/\\\/matforge.org\\\/fr\\\/research-software-documentation-practical-guide-scientists\\\/#breadcrumb\"},\"inLanguage\":\"fr-FR\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\\\/\\\/matforge.org\\\/fr\\\/research-software-documentation-practical-guide-scientists\\\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\\\/\\\/matforge.org\\\/fr\\\/research-software-documentation-practical-guide-scientists\\\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\\\/\\\/matforge.org\\\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Documentation sur les logiciels de recherche : un guide pratique pour les scientifiques\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\\\/\\\/matforge.org\\\/#website\",\"url\":\"https:\\\/\\\/matforge.org\\\/\",\"name\":\"matforge.org\",\"description\":\"\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\\\/\\\/matforge.org\\\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"fr-FR\"},{\"@type\":\"Person\",\"@id\":\"https:\\\/\\\/matforge.org\\\/#\\\/schema\\\/person\\\/2effd7bc155a5e6357f31dac970c5795\",\"name\":\"Priya Nair\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"fr-FR\",\"@id\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/f11e168d4cd2f1eff83cbb851d6cff42d81d88bb59d8831ee77468aa4a5eea88?s=96&d=mm&r=g\",\"url\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/f11e168d4cd2f1eff83cbb851d6cff42d81d88bb59d8831ee77468aa4a5eea88?s=96&d=mm&r=g\",\"contentUrl\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/f11e168d4cd2f1eff83cbb851d6cff42d81d88bb59d8831ee77468aa4a5eea88?s=96&d=mm&r=g\",\"caption\":\"Priya Nair\"},\"sameAs\":[\"http:\\\/\\\/matforge.org\"],\"url\":\"https:\\\/\\\/matforge.org\\\/author\\\/priya-nair\\\/\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Guide de documentation des logiciels de recherche","description":"Apprenez \u00e0 documenter les logiciels de recherche avec Di\u00e1taxis, Lisez-moi des mod\u00e8les, Citation.cff, Sphinx, MKDocs, lisez les documents et les r\u00e8gles pratiques.","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/matforge.org\/fr\/research-software-documentation-practical-guide-scientists\/","og_locale":"fr_FR","og_type":"article","og_title":"Guide de documentation des logiciels de recherche","og_description":"Apprenez \u00e0 documenter les logiciels de recherche avec Di\u00e1taxis, Lisez-moi des mod\u00e8les, Citation.cff, Sphinx, MKDocs, lisez les documents et les r\u00e8gles pratiques.","og_url":"https:\/\/matforge.org\/fr\/research-software-documentation-practical-guide-scientists\/","og_site_name":"matforge.org","article_published_time":"2026-08-21T14:31:34+00:00","author":"Priya Nair","twitter_card":"summary_large_image","twitter_misc":{"\u00c9crit par":"Priya Nair","Dur\u00e9e de lecture estim\u00e9e":"14 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"Article","@id":"https:\/\/matforge.org\/fr\/research-software-documentation-practical-guide-scientists\/#article","isPartOf":{"@id":"https:\/\/matforge.org\/fr\/research-software-documentation-practical-guide-scientists\/"},"author":{"name":"Priya Nair","@id":"https:\/\/matforge.org\/#\/schema\/person\/2effd7bc155a5e6357f31dac970c5795"},"headline":"Documentation sur les logiciels de recherche : un guide pratique pour les scientifiques","datePublished":"2026-08-21T14:31:34+00:00","mainEntityOfPage":{"@id":"https:\/\/matforge.org\/fr\/research-software-documentation-practical-guide-scientists\/"},"wordCount":2623,"commentCount":0,"articleSection":["Suivi des probl\u00e8mes, billets &amp; Demandes techniques"],"inLanguage":"fr-FR","potentialAction":[{"@type":"CommentAction","name":"Comment","target":["https:\/\/matforge.org\/fr\/research-software-documentation-practical-guide-scientists\/#respond"]}]},{"@type":"WebPage","@id":"https:\/\/matforge.org\/fr\/research-software-documentation-practical-guide-scientists\/","url":"https:\/\/matforge.org\/fr\/research-software-documentation-practical-guide-scientists\/","name":"Guide de documentation des logiciels de recherche","isPartOf":{"@id":"https:\/\/matforge.org\/#website"},"datePublished":"2026-08-21T14:31:34+00:00","author":{"@id":"https:\/\/matforge.org\/#\/schema\/person\/2effd7bc155a5e6357f31dac970c5795"},"description":"Apprenez \u00e0 documenter les logiciels de recherche avec Di\u00e1taxis, Lisez-moi des mod\u00e8les, Citation.cff, Sphinx, MKDocs, lisez les documents et les r\u00e8gles pratiques.","breadcrumb":{"@id":"https:\/\/matforge.org\/fr\/research-software-documentation-practical-guide-scientists\/#breadcrumb"},"inLanguage":"fr-FR","potentialAction":[{"@type":"ReadAction","target":["https:\/\/matforge.org\/fr\/research-software-documentation-practical-guide-scientists\/"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/matforge.org\/fr\/research-software-documentation-practical-guide-scientists\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/matforge.org\/"},{"@type":"ListItem","position":2,"name":"Documentation sur les logiciels de recherche : un guide pratique pour les scientifiques"}]},{"@type":"WebSite","@id":"https:\/\/matforge.org\/#website","url":"https:\/\/matforge.org\/","name":"matforge.org","description":"","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/matforge.org\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"fr-FR"},{"@type":"Person","@id":"https:\/\/matforge.org\/#\/schema\/person\/2effd7bc155a5e6357f31dac970c5795","name":"Priya Nair","image":{"@type":"ImageObject","inLanguage":"fr-FR","@id":"https:\/\/secure.gravatar.com\/avatar\/f11e168d4cd2f1eff83cbb851d6cff42d81d88bb59d8831ee77468aa4a5eea88?s=96&d=mm&r=g","url":"https:\/\/secure.gravatar.com\/avatar\/f11e168d4cd2f1eff83cbb851d6cff42d81d88bb59d8831ee77468aa4a5eea88?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/f11e168d4cd2f1eff83cbb851d6cff42d81d88bb59d8831ee77468aa4a5eea88?s=96&d=mm&r=g","caption":"Priya Nair"},"sameAs":["http:\/\/matforge.org"],"url":"https:\/\/matforge.org\/author\/priya-nair\/"}]}},"_links":{"self":[{"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/posts\/1268","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/users\/4"}],"replies":[{"embeddable":true,"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/comments?post=1268"}],"version-history":[{"count":1,"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/posts\/1268\/revisions"}],"predecessor-version":[{"id":1422,"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/posts\/1268\/revisions\/1422"}],"wp:attachment":[{"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/media?parent=1268"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/categories?post=1268"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/tags?post=1268"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}