Documentation

[johanricher]

Dans le cadre de la mise à disposition d'un outil de visualisation des indicateurs Ecosphères, il s'agit de documenter :

• Chaîne de traitement (étapes / solutions utilisées)
• Processus de mise à jour (tâches / personnes concernées)

[qloridant]

J'ai commencé la rédaction de la doc "data engineering" dans le README.md du dossier de l'etl.

[qloridant]

@Thesauruv j'ai bien noté le besoin de documentation de variables utilisées.

SI je comprends bien, cette documentation a pour objectif principal de connaître le mapping entre les champs de la base de données et les graphes.

Que penses-tu d'un tableau dans lequel chaque ligne comprendrait :

• SQL Variable Name
• Description
• JSON-LD Graph Attribute
• JSON-LD Graph Path
• Example Value

Ce qui donnerait pour exemple, sur un cas un peu complexe :

• SQL Variable Name : catalog
• Description : Nom du catalogue auquel appartient le jeu de donnée
• JSON-LD Graph Attribute : title
• JSON-LD Graph Path : dataset -> foaf:isPrimaryTopicOf (CatalogRecord) -> dcat:inCatalog (Catalog) -> title
• Example Value : GéoIDE Catalogue

On peut aussi imaginer un champ GeoDCAT-AP compatible

[Thesauruv]

@qloridant Je suis pour le principe que tout ce qui est clairement documenté dans le code n'a pas vocation à être redocumenté, ce qui est assez bien le cas des métadonnées mappées depuis la classe DCATReader jusqu'au transfert dans la base Postgres. La documentation dans le code peut être être consolidée, pour ce qui est par exemple des définitions des métadonnées (si disponible dans la documentation GeoDCAT-AP ou ISO préférentiellement, sinon vers le schéma Ecosphères) mais aussi des irrégularités observées (métadonnées non trouvée dans GeoDCAT-AP -> licence, irrégularité dans l'écriture de la propriété par rapport aux conventions DCAT -> rights_holder).

La chaîne de traitement dans Metabase n'est pas facilement accessible. Pour cette raison, je garderais le maximum de complexité en Python et minimiserais la complexité des commandes SQL. Je vois sur ce point là un refactoring, @qloridant on peut en rediscuter.

[clementmandron]

J'ai effectué plusieurs modifications sur la documentation dans l'outil (implémentation des remarques des utilisateurs lors des entretiens) :

1. Mis en évidence de 'Comment utiliser cet outil' et basculé 'Pourquoi utiliser cet outil' en bas de page
2. Modifié des astuces de lecture (exemple propriétaire, à quel seuil une organisation est classée dans autre)
3. Ajouté le mot "Astuce de lecture" (et déplacé le mot fictive, cela était confusant)
4. Ajout des astuces de lecture manquantes (points de contact, licences et conditions d'accès)
5. Ajout des émoticônes dans le titre des filtres
6. Nombre de jeux de données avant la table des jeux de données
7. Réorganisation des sections

Pour information @Thesauruv @johanricher @qloridant