Documentation

Ce module explique pourquoi il est important de bien documenter les données.

Dans cette vidéo (09:47), vous découvrirez pourquoi la documentation est essentielle à la gestion et à la publication des données. Nous aborderons la correspondance des données, les relations entre les données et les métadonnées.

Si vous ne pouvez pas regarder la vidéo intégrée, vous pouvez la télécharger localement (MP4 - 35.2 Mo)

Transcription de la présentation

Cliquez pour développer

Diapositive 1 – Fondation : documentation

Cette présentation explique l’importance de la documentation dans la gestion et la publication des données. Vous y découvrirez la mise en correspondance des données, les relations entre les données et les métadonnées.

Diapositive 2 - Documentation

Dans les précédentes présentations sur la Fondation, nous avons étudié les différents éléments qui constituent vos données, ainsi que les structures utilisées pour les organiser et les stocker. Nous allons maintenant nous intéresser à la manière de documenter ces données et d’expliquer l’usage auquel elles sont destinées. Comme l’a déclaré le réalisateur Steven Spielberg : « Les gens ont oublié comment raconter une histoire. Les histoires n’ont désormais ni milieu ni fin. Elles ont généralement un début qui ne cesse jamais de commencer. » La documentation permet de raconter l’histoire de votre projet ou de votre jeu de données. Elle doit donc en présenter clairement le début, le déroulement et la finalité. Pour construire cette histoire, certaines questions doivent être posées à chaque étape. Au début, il convient de se demander : Quels étaient les objectifs du projet ? Dans quel but le jeu de données a-t-il été créé ?

Au cours du projet : Qu’avons-nous réellement fait ? Quels résultats avons-nous obtenus ?

À la fin du projet : Quels objectifs n’avons-nous pas atteints, et pourquoi ? Quelles sont les prochaines étapes ?

Diapositive 3 - Concepts clés

Pour bien documenter vos données et faciliter leur utilisation, aussi bien par vous-même que par de futurs utilisateurs, trois étapes essentielles doivent être suivies :

Procéder, si nécessaire, au formatage de vos données conformément aux formats et standards existants
Planifier les différentes étapes de traitement et de transfert de vos données
Créer des métadonnées pertinentes pour décrire vos données.

Diapositive 4 – Formatage des données

Nous commencerons par voir comment décrire vos données. Nous expliquerons ensuite comment les adapter d’une structure à une autre, avant d’aborder la création des métadonnées qui les accompagnent. Commençons par le formatage des données, également appelé mise en correspondance des champs. Cette opération consiste à déterminer comment les champs d’un jeu de données peuvent être transformés ou associés aux champs d’une autre structure. Elle consiste à « identifier le ou les champs sources dans le jeu de données A et à déterminer leurs champs correspondants dans le jeu de données B ». Dans cet exemple, le jeu de données A comprend 10 colonnes : * des champs de type entier, représentés par les carrés violets, * quelques champs booléens, représentés par les triangles rouges * quelques champs de type date, représentés par les pentagones bleus * quelques champs de type texte, représentés par les étoiles vertes à 8 branches * et quelques champs de type complexe

Diapositive 5 – Formatage des données

Le jeu de données B comporte une structure différente, composée de 15 champs au total. Nous devons déterminer quels champs du jeu de données A correspondent à ceux du jeu de données B

Diapositive 6 – Formatage de A vers B

Pour établir cette correspondance, nous devons définir les relations entre les champs des deux jeux de données.

Par exemple, le jeu de données A et le jeu de données B possèdent tous deux un champ ID. Nous pouvons donc relier directement ces deux champs. Il s’agit d’une correspondance un à un. Question : Voyez-vous d’autres correspondances un à un ? Réponse : State, Exp? et Pink Elephant! Un autre type de relation est la correspondance un à plusieurs. Dans ce cas, un seul champ du jeu de données A correspond à deux champs ou plus dans le jeu de données B. Le champ Date en est un exemple. Il peut également arriver que plusieurs champs du jeu de données A contiennent des informations destinées à plusieurs champs du jeu de données B. C’est souvent le cas des champs de notes ou de remarques.

Diapositive 7 - Planification des transferts de données - Relations entre les données

En réalité, il existe six relations :

Certains champs peuvent être mis en correspondance un à un (1:1), ce qui signifie qu’une colonne du jeu de données A correspond directement à une colonne du jeu de données B
Certains champs suivent une correspondance plusieurs à un (∞:1) : les contenus de plusieurs colonnes du jeu de données A sont regroupés ou concaténés dans une seule colonne du jeu de données B
Certains champs suivent une correspondance un à plusieurs (1:∞) : une colonne du jeu de données A doit être divisée en deux champs ou plus afin de correspondre aux champs du jeu de données B.
Certains champs peuvent ne pas encore exister, ce qui correspond à une relation zéro à un (0:1) : certaines informations absentes du jeu de données A doivent être ajoutées dans une nouvelle colonne afin de correspondre à un champ existant du jeu de données B.
Certains champs peuvent ne pas avoir de champ de destination, ce qui correspond à une relation un à zéro (1:0) : certaines informations présentes dans le jeu de données A ne correspondent à aucun champ existant dans le jeu de données B
Certains champs présentent une correspondance plusieurs à plusieurs (∞:∞) : les informations du jeu de données A sont réparties dans plusieurs champs qui ne correspondent pas directement à ceux du jeu de données B

Diapositive 8 - Planification des transferts de données - Transformations

La manière de traiter les données varie selon le type de correspondance.

un à un (1:1) – Vérifiez attentivement le type de chaque champ. S’ils sont différents, certaines transformations seront nécessaires.
Plusieurs à un (∞:1) – Les valeurs de plusieurs champs devront être regroupées pour être intégrées dans un seul champ.
Un à plusieurs (1:∞) – Le contenu d’un champ devra être séparé, puis réparti dans plusieurs champs distincts.
zéro à un (0:1) – Vérifiez si les champs manquants peuvent être complétés. Les informations sont-elles présentes dans un champ de notes ? Si oui, comment les récupérer et les intégrer dans les champs correspondants ?
un à zéro (1:0) – Vous devrez soit écarter les données, soit créer un nouveau champ. Si aucun champ correspondant n’existe dans le jeu de données de destination, demandez-vous s’il est possible ou pertinent d’en ajouter un?
plusieurs à plusieurs (∞:∞) – « Quelle situation compliquée ! » Cela signifie généralement que les données sources sont très désorganisées et qu’elles nécessiteront un nettoyage approfondi avant leur mise en correspondance.

Diapositive 9 – Planification du transfert des données : document de correspondance des champs

Voici à quoi peut ressembler un document de correspondance des champs. Il décrit les relations entre les champs et précise, autant que possible, les transformations à effectuer sur les données.

Diapositive 10 - Métadonnées

Nous avons beaucoup parlé de la documentation des structures qui contiennent vos données. Cependant, il est tout aussi important de documenter les informations qui permettent de comprendre leur contexte. Ces informations sont appelées métadonnées, c’est-à-dire des données qui décrivent vos données. Comme indiqué dans la section consacrée à la qualité des données, « vos métadonnées doivent être suffisamment détaillées pour permettre à un tiers d’utiliser ou de réutiliser les données sans avoir à consulter la source d’origine ».

Diapositive 11 - Métadonnées

Nous reviendrons plus en détail sur ce sujet dans les prochaines sessions. Pour l’instant, retenez qu’une bonne documentation doit comprendre :

Un titre – Il doit être descriptif, facile à retenir et, si possible, unique. Il est également utile d’inclure une date dans le nom du jeu de données afin de faciliter le suivi des différentes versions.
Une description générale – Elle doit expliquer les raisons de la création du jeu de données et fournir des informations générales sur sa couverture géographique, temporelle et taxonomique. Elle doit également permettre aux utilisateurs potentiels de comprendre les usages possibles des données sans transformation supplémentaire.
La provenance des données – Si vous ne les avez pas collectées ou mesurées vous-même, indiquez d’où elles proviennent et qui vous les a fournies.
L’historique des données – Le jeu de données a-t-il déjà fait l’objet de traitements ? Certains champs ont-ils été modifiés ou transformés par rapport aux données d’origine ?
Une déclaration sur l’exactitude des données – En vous appuyant sur les notions d’exactitude, de précision, d’erreur et d’incertitude abordées précédemment, indiquez tout problème lié au jeu de données dont les utilisateurs devraient avoir connaissance.
Les dates et la durée de validité – Quand le jeu de données sera-t-il disponible ? Pendant combien de temps restera-t-il valide ? Sera-t-il mis à jour et, si oui, à quelle fréquence ?
La définition des champs – Décrivez le format de chaque champ et le type de données qu’il contient. Précisez également les opérations de nettoyage ou de transformation appliquées aux données d’origine. Ces informations sont essentielles pour mettre les données en correspondance avec un standard tel que Darwin Core
La méthode de collecte – Comment les données ont-elles été collectées ? Des protocoles particuliers ont-ils été utilisés et peuvent-ils influencer leur adéquation à l’usage prévu (fitness for use)?
Une déclaration sur la complétude des données – Quelles informations sont absentes du jeu de données, et pour quelles raisons ?
Les conditions d’utilisation et les restrictions – Dans quels contextes et de quelle manière les données peuvent-elles être utilisées ? La plupart des portails, notamment le GBIF, exigent l’utilisation de licences très ouvertes. Il est donc essentiel de bien comprendre les conditions fixées par les détenteurs des données et leurs institutions.
Les responsables et les personnes-ressources – Précisez l’institution responsable du jeu de données tel qu’il vous a été transmis et, si possible, le nom de la personne qui l’a créé. Indiquez également les coordonnées du contact technique chargé de sa publication.

Diapositive 12 - Conclusion

Cette vidéo fait partie d’une série de présentations utilisées dans le cadre de la formation du GBIF sur la mobilisation des données sur la biodiversité. Le programme de cette formation a été initialement élaboré dans le cadre du Programme BID (Biodiversity Information for Development), financé par l’Union européenne. Cette présentation a été initialement créée par Sharon Grant et mise en voix par Sophie Pamerlon.