# Check-liste pour la Documentation et la Citation des Logiciels

Romain David, Solange Santos, Shelley Stall, Alison Specht, Pedro Luiz Pizzigatti Corrêa, Jeaneth Machicao, Nobuko Miyairi, Yasuhiro Murayama, Margaret O'Brien, Lesley Wyborn, et al.

<figure><img src="image_1.png" /></figure>

## To cite this version:

Romain David, Solange Santos, Shelley Stall, Alison Specht, Pedro Luiz Pizzigatti Corrêa, et al. Check-liste pour la Documentation et la Citation des Logiciels. 2023, 10.5281/zenodo.7847721. hal-04829060

HAL Id: hal-04829060

https://hal.science/hal-04829060v1

Submitted on 10 Dec 2024

HAL is a multi-disciplinary open access archive for the deposit and dissemination of scientific research documents, whether they are published or not. The documents may come from teaching and research institutions in France or abroad, or from public or private research centers.

L'archive ouverte pluridisciplinaire HAL, est destinée au dépôt et à la diffusion de documents scientifiques de niveau recherche, publiés ou non, émanant des établissements d'enseignement et de recherche français ou étrangers, des laboratoires publics ou privés.

<figure><img src="image_2.png" /></figure>
# Partagez vos logiciels –
CHECK-LISTE POUR LA DOCUMENTATION ET LA
CITATION DES LOGICIELS

Bienvenue dans "Votre parcours Science Ouverte"!

Planifiez, gérez et partagez vos logiciels. Utilisez cette check-liste pour améliorer vos pratiques de gestion et de partage de logiciels.

## Audience cible

**Principale:** Équipes ou chercheur.e.s dans le cadre des projets

**Secondaire:** Équipes ou responsables de projets

Cette check-liste est générique et devra être ajustée en fonction des exigences de votre établissement, laboratoire, équipe de recherche et/ou financeur.

## A. PLANIFIEZ ET GÉREZ VOTRE LOGICIEL PENDANT VOTRE PROJET DE RECHERCHE

1. Choisissez le format et organisez vos fichiers logiciels:

a. **Utilisez** des outils logiciels libres dans la mesure du possible.

b. Choisissez des noms de fichiers descriptifs et utiles que les humains et les machines peuvent lire. Des exemples d'idées pour améliorer la convention de nom de fichier peuvent inclure, 1) L'utilisation de délimiteurs choisis tels que "-" pour relier les termes ensemble et "_" pour séparer différentes informations ; 2) Éviter les caractères spéciaux (par exemple, $), les espaces et la ponctuation ; 3) Créer des noms significatifs et des métadonnées qui soient explicites sur le contenu ; 4) Utiliser des méthodes qui facilitent le tri par défaut telles que le format de date AAAA-MM-JJ (norme internationale). Voir Jenny Bryan [How to name files](https://www.codinghorror.com/2012/07/how-to-name-files.html)

c. Déterminez la structure hiérarchique des dossiers et des fichiers pour le projet. Soyez cohérent, utilisez un répertoire par projet, séparé par fonction (par exemple, données, code) et par sortie (par exemple, figures, résultats). Assurez-vous que les données brutes d'origine sont séparées, ne peuvent pas être modifiées et que des copies des données brutes sont faites pour être modifiées. Pour plus d'informations, reportez-vous au [compendium "file-structure"](https://en.wikipedia.org/wiki/Compendium_file-structure) développé par le Turing Way.

d. Créez un ou plusieurs fichiers README ou LISEZMOI. Rassemblez les informations qui seront essentielles pour décrire et citer votre logiciel ultérieurement, notamment les auteur.e.s (contribut.eur.rice.s), le nom du projet/logiciel, les versions, les standards de codage, les dépendances, les environnements, les tests et les données concernant la maintenance du logiciel.

* En fonction de la structure et de la complexité de votre fichier, vous souhaiterez peut-être un fichier README pour chaque type de logiciel (par exemple : nettoyage des données, analyse) ainsi qu'un autre pour décrire l'ensemble de la structure du fichier. Un outil utile : [https://readme.so](https://readme.so). Gardez votre fichier README à jour.

2. Gérez vos logiciels plus efficacement grâce à la gestion des versions et aux carnets de notes pour logiciel (notebooks):
<figure><img src="image_3.png" /></figure>

a. Utilisez un système de contrôle de version pour suivre les modifications de fichiers ou l'historique d'un projet (par exemple, les mises à jour logicielles). Des plateformes telles que GitHub, GitLab, ou Open Science Framework (OSF) offrent des fonctionnalités de travail collaboratif et de sauvegarde en ligne supplémentaires.

b. Utilisez un carnet de notes pour logiciel (par exemple, Jupyter, R Markdown) pour rendre votre recherche plus facile à comprendre et plus reproductible.

c. Soyez attentif à respecter les licences d'utilisation des logiciels créés par d'autres.

### 3. Stockez et sauvegardez vos fichiers logiciels :

a. Protégez vos fichiers en vous assurant qu'ils sont automatiquement sauvegardés par un système de confiance. Profitez des services de sauvegarde de votre établissement s'ils sont offerts. Il est préférable que le système de sauvegarde se trouve dans un emplacement géographique différent (par exemple, un service de stockage "dans le cloud").

## B. PARTAGEZ OUVERTEMENT VOTRE LOGICIEL

Suivez ces étapes lorsque votre recherche franchit une étape importante et avant la publication.

### 1. Sélectionnez votre entrepôt d'archivage de logiciels

a. Choisissez un entrepôt. Les plateformes de développement de logiciels telles que GitHub ne sont pas des solutions de conservation à long terme. Prévoyez-en une adaptée à l'archivage à long terme et identifiez l'entrepôt que vous utiliserez (domaine, institutionnel, général) avant de citer votre logiciel. L'adhésion à [SciCodes membership](https://www.sciedoc.org/sci-codes) comprend des domaines couramment utilisés et des entrepôts généraux.

b. Déterminez les métadonnées dont vous aurez besoin. Par exemple: Rendre votre code citable via Zenodo et GitHub et utiliser la Sandbox de Zenodo vous permet de voir les métadonnées supplémentaires dont vous aurez besoin, y compris les ORCID pour les auteur.e.s, les identifiants associés (par exemple, les DOI d'articles), les informations de financement, etc. et le fichier "CodeMeta" qui est créé.

c. Pour les logiciels/modèles de simulation, le modèle et la configuration doivent généralement être conservés. La communauté des modèles "EarthCube" a développé un cadre ([framework to guide](https://www.earthcube.org/labs framework-to-guide)) pour vous indiquer ce qu'il faut préserver de vos recherches et qui est facile à adapter.

### 2. Documentez votre logiciel avant de le déposer - fichiers README, métadonnées et licences

a. Préparez vos métadonnées. (recommandé)

De nombreux entrepôts d'archivage de données fournissent des conseils sur le type de documentation nécessaire pour rendre vos données compréhensibles. Lorsque ces instructions ne sont pas disponibles, suivez les instructions du Guide [CodeMeta](https://www codemeta.org/).

b. Attribuez une licence à vos logiciels (obligatoire)

Sélectionnez et utilisez une licence libre. Utilisez le site "[Choose an open-source license](https://www.opensource.org/licenses/index.html)" pour choisir la bonne licence.
<figure><img src="image_4.png" /></figure>

3. Déposez vos logiciels auprès de l'entrepôt sélectionné

a. Ajoutez des instructions à votre plateforme de développement (par exemple, GitHub) sur la façon de citer votre logiciel. Utilisez le format de fichier de citation Citation File Format. Le groupe de travail FORCE11 "Software Citation Implementation" a préparé des conseils détaillés pour les développeur.e.s et les auteur.e.s.

b. Assurez-vous que l'entrepôt affiche clairement votre citation au format préféré.

C. CITEZ TOUS LES LOGICIELS

1. Incluez votre déclaration de disponibilité du logiciel si elle a un impact significatif sur votre recherche et/ou si votre recherche n'est pas reproductible sans elle. La déclaration doit inclure :

a. Une très brève description de l'utilisation du logiciel

b. Un entrepôt comprenant un DOI/PID pour votre logiciel archivé (par exemple Zenodo)

c. La version du logiciel utilisée et archivée

d. La licence associée (libre et autres conditions d'accès)

e. Un lien vers la plateforme de développement (par exemple, GitHub)

f. Dans la section méthodologie de votre article : décrivez le fonctionnement de votre logiciel en ce qui concerne votre recherche

g. Incluez la ou les citations du logiciel dans vos références en utilisant le DOI/PID du logiciel archivé dans l'entrepôt.

2. Utilisez la déclaration de disponibilité et la check-liste des citations d'AGU (the availability statement and citation checklist) pour vous assurer que vos citations et déclarations de disponibilité sont complètes. Voir les conseils sur le partage de données et de logiciels pour les auteur.e.s d'AGU (Data and Software Sharing Guidance for Authors) pour plus de détails.

Références

Chue Hong NP, Allen A, Gonzalez-Beltran A, et al. (2019). Software Citation Checklist for Developers (0.9.0). Zenodo. https://doi.org/10.5281/zenodo.3482769

Chue Hong NP, Allen A, Gonzalez-Beltran A, et al. (2019). Software Citation Checklist for Authors (0.9.0). Zenodo. https://doi.org/10.5281/zenodo.3479199

Liens rapides vers les check-listes connexes:

• Check-liste présence numérique

- Check-liste pour la Documentation et la Citation des Données

Pour suggérer des mises à jour, svp envoyez un email à datahelp@agu.org. Incluez le DOI et le nom de la check-liste dans votre email, merci.
**Pour citer cette check-liste:** David, Romain, Santos, Solange, Stall, Shelley, Specht, Alison, Corrêa, Pedro Luiz Pizzigatti, Machicao, Jeaneth, Miyairi, Nobuko, Murayama, Yasuhiro, O'Brien, Margaret, Wyborn, Lesley, Vellenich, Danton Ferreira, & Mabile, Laurence. Check-liste pour la Documentation et la Citation des Logiciels. Zenodo. https://doi.org/10.5281/zenodo.7847721

**Traduction de l'anglais:** Romain David, Laurence Mabile