search

etalab / doc.data.gouv.fr

Documentation du site data.gouv.fr.
https://doc.data.gouv.fr
MIT License
7 stars 53 forks source link

Liste des articles à rédiger pour enrichir la documentation #36

Closed bboulesteix closed 5 years ago

bboulesteix commented 5 years ago

Pourquoi toucher aux articles présents sur doc.data.gouv.fr ?

Problèmes

Il y a deux problèmes avec doc.data.gouv.fr dans son état actuel :

  1. Les articles de la documentation sont datés pour certains, voire anachroniques. On peut par exemple encore y lire des phrases comme celle qui suit : Fin 2015, de nouveaux outils intensifieront les conversations entre réutilisateurs. Nous en sommes fin 2018, une mise à jour semble donc s’imposer, d’abord sur le fond (textes), puis sur la forme (design) — cette issue se concentre sur les textes.
  2. La classification des articles par type d’utilisateur supposé (citoyen, intégrateur, développeur…), bien qu’intéressante, ne correspond pas avec ce qui est généralement attendu d’une documentation, ou d’un site d’aide, à savoir : un dépannage en cas de problème. Les lecteurs arrivent sur une documentation parce qu’ils cherchent la réponse à une question précise, ils ne sont donc pas disposés à tout lire — comme le montrent les recherches de Nielsen en la matière.

Solutions proposées

À chaque problème, sa solution :

  1. Les articles sont datés, supprimons-les, s’ils sont caduques ; ou mettons-les à jour, s’ils sont encore pertinents. C’est aussi simple que ça. 🙂
  2. Les articles sont classés selon des types d’utilisateurs potentiels, classons-les plutôt selon les actions que les utilisateurs cherchent à accomplir quand ils utilisent data.gouv.fr, actions qui peuvent transcender les catégories d’utilisateur. Par exemple, dans la même journée, un développeur peut très bien avoir un problème de clef d’API et l’envie de changer l’adresse e-mail associée à son profil — deux tâches bien différentes. À chaque action de l’utilisateur doit donc correspondre un article d’aide qui explique comment la mener à bien.

Rédaction des articles

Pour être justifié, chaque article doit selon moi correspondre à une tâche qu’un utilisateur peut chercher à accomplir — on parle aussi de user story. Garder en tête ce que les utilisateurs cherchent à accomplir sur data.gouv.fr devrait nous éviter l’accueil qui consiste à écrire des article d’aide pour dire ce que nous avons envie de dire, plutôt que ce que les gens ont besoin de savoir. Je n’invente rien sur ce point, cette méthodologie ayant été popularisée et présentée par une ancienne de gov.uk dans une vidéo publiée sur Vimeo.

Les scenario peuvent être exprimés de façon canonique, en suivant la structure ci-dessous :

En tant que {type d’utilisateur}, je veux {faire quelque chose}, pour {répondre à un besoin}.

Catégories envisagées

N.-B. Il s’agit d’une liste de travail, quelque chose de provisoire, en attendant d’y voir plus clair et de mieux comprendre les besoins des utilisateurs.

Nous pourrions aussi imaginer les catégories suivantes :

Le hic avec ce second classement des articles, c’est que la catégorie Utiliser data.gouv.fr sera sans doute bien plus fournie que les deux autres. Je penche donc plus en faveur du classement évoqué un peu plus haut, celui qui repose sur 5 catégories.

Sections de la documentation

En admettant que nous partions sur 5 catégories d’articles, voici ce que nous pourrions avoir comme articles à l’intérieur de chacun d’entres elles — avec, pour chaque article, la user story associée.

À propos de data.gouv.fr

User stories Articles associés
En tant qu’utilisateur, je veux savoir ce qui peut-être publié sur data.gouv.fr, pour déterminer si mon jeu de données est éligible à une mise en ligne. Que publier sur data.gouv.fr et comment le publier
En tant qu’utilisateur, je veux comprendre la différence entre un utilisateur et une organisation, pour publier mon jeu de données sous la bonne bannière. Différences entre un utilisateur et une organisation
En tant qu’utilisateur, je veux signaler un jeu de données ou une réutilisation, pour demander aux modérateurs de la plateforme de le retirer. Signaler un contenu

Gestion du compte

User stories Articles associés
En tant qu’utilisateur, je veux créer un compte, pour contribuer sur data.gouv.fr. Créer un nouveau compte
En tant qu’utilisateur, je veux modifier mon compte, pour changer mon adresse e-mail de contact. Voir ou modifier un compte
En tant qu’utilisateur, je veux supprimer mon compte, pour cesser d’utiliser data.gouv.fr. Fermer un compte

Jeux de données

User stories Articles associés
En tant qu’utilisateur, je veux savoir comment utiliser la barre de recherche, pour trouver ce qui m’intéresse. Rechercher un jeu de données
En tant qu’utilisateur, je veux télécharger un jeu de données, pour en le réutiliser. Télécharger une ressource
En tant qu’utilisateur, je veux comprendre la différence entre un jeu de données et une ressource, pour comprendre de quoi on me parle. Différences entre un jeu de données et une ressource
En tant que producteur, je veux publier un jeu de données, pour contribuer à l’open data. Publier un nouveau jeu de données
En tant que producteur, je veux mettre à jour un jeu de données existant, pour ne pas avoir à en créer un nouveau. Mettre à jour un jeu de données ou une ressource
En tant que producteur, je veuxconfigurer un moissonneur, pour publier des jeux de données déjà en ligne sur mon propre site. Demander à data.gouv.fr de moissonner votre site
En tant que producteur, je veux retirer un jeu de données précédemment publié, pour supprimer des données obsolètes. Supprimer un jeu de donnée ou une ressource
En tant que producteur, je veux connaître les différences entre les licences proposées, pour savoir laquelle choisir. Choisir une licence
En tant que producteur, je veux transférer les droits d’administration d’un jeu de données vers une organisation, pour éviter de le supprimer et le recréer. Transférer un jeu de données vers un autre compte

Réutilisations et discussions

User stories Articles associés
En tant que réutilisateur, je veux mettre en avant ma réutilisation, pour la montrer à d’autres personne. Associer une réutilisation à un jeu de données
En tant que réutilisateur, je veux modifier ma réutilisation, pouren changer le titre. Modifier ou supprimer une réutilisation
En tant qu’utilisateur, je veux contacter un producteur, pour lui poser une question au sujet de l’un de ses jeux de données. Ouvrir une discussion sur un jeu de données
En tant que producteur, je veux suivre les commentaires publiés sur mes jeux de données, pour répondre aux questions qui me sont posées. Modérer une discussion

Organisations

User stories Articles associés
En tant qu’administrateur, je veux créer une organisation, pour rassembler tous mes utilisateurs. Créer une nouvelle organisation
En tant qu’administrateur, je veux supprimer mon organisation, pour en signifier la fin. Supprimer une organisation
En tant qu’administrateur, je veux ajouter un utilisateur à mon organisation, pour agrandir mon équipe. Ajouter un utilisateur à une organisation
En tant qu’administrateur, je veux retirer un utilisateur de mon organisation, pour mettre la liste de ses membres à jour. Retirer un utilisateur d’une organisation
En tant qu’utilisateur, je veux suivre une organisation, pour être tenu au courant de ses nouvelles publications. Suivre les publications d’une organisation
En tant qu’utilisateur, je veux rejoindre une organisation à laquelle je contribue, pour figurer dans la liste de ses membres. Demander à rejoindre une organisation existante
En tant qu’utilisateur, je veux connaître la différence entre administrateur d’une organisation et éditeur, pour savoir quel niveau de permission accorder aux nouveaux membres. Différences entre administrateur et éditeur

Résumé des articles à rédiger

À propos de data.gouv.fr

Gestion du compte

Jeux de données

Réutilisations et discussions

Organisations

Rédaction en pause

Les articles suivants attendront que les fonctionnalités qu’ils décrivent soient opérationnelles :

Angles morts

Cette issue ne couvre pas :

abulte commented 5 years ago

Top 💪 👏

J’aime bien les 5 catégories.

Je pense à quelques sujets supplémentaires à traiter (non exhaustif):

abulte commented 5 years ago

Ok j’ai oublié de lire le dernier paragraphe apparemment :-) Ou mettrai-t-on les obligations réglementaires du coup ?

bboulesteix commented 5 years ago

Merci d’avoir pris le temps de lire l’issue @abulte.

Pour te répondre :

  1. Je ne suis pas certain de bien comprendre ce que tu entends par transfert de données. Je veux bien que tu m’en dises un peu plus. 🙂 S’il s’agit d’une autre façon de publier un jeu de données sur data.gouv.fr, le transfert d’un jeu de données peut faire l’objet d’une section à part entière dans l’article Publier un nouveau jeu de données. Mais j’ai peut-être mal compris de quoi il en retournait. 🤔
  2. Si les moissonnages concernent l’API, la documentation qui les concerne peut figurer dans celle de l’API. S’il s’agit simplement d’une autre façon de publier un jeu de données, alors les moissonnages peuvent faire l’objet d’une section dans l’article Publier un nouveau jeu de données — au même titre que la publication à la main ou par l’intermédiaire de l’API, par exemple.
  3. Pour les obligations réglementaires, ça dépend. 😎 Si l’obligation en question concerne tous les jeux de données publiés sur data.gouv.fr, alors elle peut faire l’objet d’un article sur doc.data.gouv.fr (catégorie à déterminer). Si l’obligation ne concerne qu’un seul jeu de donné, alors elle doit selon moi figurer dans la description du jeu de données concerné par l’obligation — à la manière de ce qui se fait dans les repo GitHub, puisque chaque repos peut définir sa propre licence d’utilisation. En gros, j’aimerais que nous traitions très peu — voire aucun — cas spécifique sur doc.data.gouv.fr, la documentation doit valoir pour la majorité des utilisateurs et la majorité des jeux de données, d’après moi.

J’espère ne rien avoir oublié.

abulte commented 5 years ago
  1. Il est possible de transférer un JDD depuis un utilisateur ou une organisation vers un autre utilisateur ou organisation. Effectivement ça a sa place dans le cycle de vie d'un JDD.
  2. Le moissonnage est initié via l'administration par le producteur, il s'agit effectivement d'une autre façon de publier un JDD.
  3. Les obligations concernent plusieurs jeux de données qui seront déposés par plusieurs producteurs (IRVE : une obligation, N producteurs, Y JDD ; profil d'acheteur : une obligation, N producteurs, Y JDD) et nous avons besoin d'un endroit pour expliquer aux producteurs comment faire (rappel des obligations puis comment les remplir). Il est à mon avis cohérent que tout cela se trouve à côté de la doc générale d'utilisation de data.gouv puisque le dit producteur devra apprendre à se servir du site de manière générale (créer un compte, publier un jeu de données...). Mais on peut aussi imaginer un autre site (encore une fois, besoin d'un point d'accès bien identifié à ces docs) avec des liens vers la doc générale.
bboulesteix commented 5 years ago

Merci pour ton commentaire @abulte. Pour te répondre à mon tour, dans l’ordre :

  1. C’est noté, la notion de transfert de jeu de données aura sa place dans la documentation. 🙂
  2. J’hésite à consacrer un article entier au moissonnage, car la procédure me semble plus complexe que l’ajout d'un jeu de données à la main, de façon ordinaire. À voir.
  3. Je crois que j’avais sous-estimé la nécessité de parler des obligations réglementaires dans la documentation. À la lumière de tes explications, je me rends compte qu’il va falloir leur consacrer des articles sur doc.data.gouv.fr — ce qui me semble préférable à la création d’un autre sous-domaine.
abulte commented 5 years ago
  1. 👍
  2. En effet, un article entier ne serait pas du luxe.
  3. 👍
bboulesteix commented 5 years ago

Issue fermée par : https://github.com/etalab/doc.data.gouv.fr/pull/56 🎉

AntoineAugusti commented 5 years ago

Je prends la suite de ton commentaire @bboulesteix, https://github.com/etalab/doc.data.gouv.fr/issues/36#issuecomment-426264527.

Je crois que j’avais sous-estimé la nécessité de parler des obligations réglementaires dans la documentation. À la lumière de tes explications, je me rends compte qu’il va falloir leur consacrer des articles sur doc.data.gouv.fr — ce qui me semble préférable à la création d’un autre sous-domaine.

Peux-tu me dire ce que tu as en tête ? Dans #70 il est question de supprimer du contenu expliquant l'open data, le cadre réglementaire français. Où va-t-il se retrouver ?

Il y a également des pages spécifiques de data.gouv.fr qui traitent de redevances / licences (https://www.data.gouv.fr/fr/Redevances, https://www.data.gouv.fr/fr/licences). Est-il prévu de renvoyer encore vers ces pages ou de migrer le contenu ici ?

abulte commented 5 years ago

Il y a également des pages spécifiques de data.gouv.fr qui traitent de redevances / licences (https://www.data.gouv.fr/fr/Redevances, https://www.data.gouv.fr/fr/licences). Est-il prévu de renvoyer encore vers ces pages ou de migrer le contenu ici ?

Sur ce sujet précis : ces pages ne sont pas migrables (facilement) car leurs URLs sont référencées dans des textes de loi.

bboulesteix commented 5 years ago

Je n’ai pas prévu de supprimer les pages statiques de data.gouv.fr — ce qui ne veut pas dire que je les trouve parfaites. 🙂 En revanche, j’ai prévu de supprimer la section FAQ de doc.data.gouv.fr, celle dont le titre est Découvrir l’open data, car :

  1. Il ne s’agit pas d’une foire aux questions (FAQ) mais bien d’articles de documentation ;
  2. L’approche qui consiste à écrire un article par type d’utilisateur potentiel ne me convient pas ;
  3. Je trouve ces articles un peu bavards.

Cela dit, il n’est pas question de tout mettre au feu. La section FAQ contient des informations utiles, que j’ai prévu de reprendre pour enrichir des articles qui existent déjà. C’est la raison pour laquelle la pull-request censée supprimer la section FAQ (#70) est en pause.