Aller au contenu principal

Bonne pratique pour bien documenter un projet

Voici les éléments que l'on devrait pouvoir consulter facilement: 

  • Contexte de la collecte de données
  • Méthodes de collecte de données 
  • Structure et organisation des fichiers de données 
  • Les sources des données utilisées 
  • Validation des données et processus d'assurance qualité
  • Transformations des données brutes par l'analyse 
  • Information sur la confidentialité, l'accès ou les conditions d'utilisation des données 
  • Nom des variables et leur description
  • Explication du code et de la méthode de classification utilisée
  • Algorithmes utilisés pour transformer les données 
  • Format de fichier et logiciel (incluant la version) utilisés

Il est important de conserver les protocoles de recherche avec les données (procédure opérationnelle normalisée pour les collectes de données). Il faut bien documenter tout au long du projet et s'assurer de conserver cette documentation qui sera essentielle pour comprendre les données, reproduire ou repliquer la recherche. 

 

Une bonne façon de document est de faire un fichier README. 

Un fichier README est un fichier texte qui présente et explique un projet. Il contient des informations généralement nécessaires pour comprendre en quoi consiste le projet. C'est un moyen facile de répondre aux questions que votre public aura probablement sur la façon d'utiliser vos données de recherche et également de collaborer avec vous.

Vous pourrez l'enregistrer dans le répertoire de niveau supérieur du projet. C'est là que débutera quelqu'un qui est nouveau dans votre projet.

(Les services d'hébergement de code tels que GitHub, Bitbucket et GitLab rechercheront également votre fichier README et l'afficheront avec la liste des fichiers et répertoires de votre projet.)

 

Créez un fichier README ou LISEZ-MOI pour chaque fichier de données, dans la mesure du possible. Il convient également de décrire un "ensemble de données" qui contient plusieurs fichiers associés, au format identique, ou des fichiers qui sont logiquement regroupés pour être utilisés (par exemple, une collection de scripts Matlab). Le cas échéant, décrivez également la structure de fichiers qui contient les fichiers de données associés.

 

Nommez le fichier README afin qu'il soit facilement associé aux fichiers de données qu'il décrit.

Écrivez votre document README sous forme de fichier texte, en évitant autant que possible les formats propriétaires tels que MS Word. Formatez le document README pour qu'il soit facile à comprendre (par exemple, séparez les informations importantes avec des lignes vierges, plutôt que d'avoir toutes les informations dans un long paragraphe).

 

Formatez plusieurs fichiers README de manière identique. Présentez les informations dans le même ordre, en utilisant la même terminologie.

Utilisez des formats de date normalisés.

(Format suggéré: norme de date W3C / ISO 8601, qui spécifie la notation standard internationale de YYYY-MM-DD ou YYYY-MM-DDThh: mm: ss.)

Vous pouvez télécharger le modèle suivant pour plus de détails.