Documentation à destination des utilisateurs

johanricher commented 2 years ago

User stories

ETQ personne interessée par le projet, j'ai besoin d'avoir des réponses à mes questions pour mieux comprendre le projet et le fonctionnement du service catalogue.data.gouv.fr

Contexte

Le principe générale est de designer le service de sorte à ce qu'il ne nécessite pas de documentation. Toutes les questions et blocages devraient être adressés pendant l'utiisation, sans sortir du workflow de l'utilisateur et sans navigation nécessaire vers une page dédiée. Le feedback venant de vrais utilisateurs permettra d'identifier les blocages et incompréhensions à résoudre.

A défaut, dans un premier temps une documentation sera un palliatif.

Critères d'acceptation

Apporter des réponses aux questions suivantes :

[x] Comment contacter les personnes responsables du projet ? (cf. #370)
[x] Quelle est la liste des organisations / catalogues sur l'instance ? (cf. #358)
[x] Comment s'enregistrer (explications Datapass) ? (cf. #124)
[x] Comment créer une organisation (process de demande et validation avant la création) ? (cf. #334)
[ ] Comment importer un catalogue préexistant ? (cf. #343)

Implémentation

[x] Créer une page dans le wiki
[x] @florimondmanca Créer une page de doc technique à partir de l'import MC
[ ] Répondre aux premières questions identifiées

DaFrenchFrog commented 2 years ago

@johanricher La page FAQ n'est généralement une solution adaptée qu'en dernier ressort et lorsque l'on ne trouve pas d'autre moyen pour répondre aux questions d'un utilisateur.

Voici une proposition de page d'accueil qui me semble répondre à la plupart des questions spécifiées et qui sert de présentation synthétique du projet (inutile d'être exhaustif sur la home, on proposera un lien vers une documentation plus détaillée qui pourrait être un wiki sur ce repo par exemple).

Également je propose de répondre à la question du contact de l'équipe avec le ticket #370 qui me semble une solution optimale à ce niveau d'avancement du projet et qui sera rapide à implémenter.

Qu'en penses-tu ?

johanricher commented 2 years ago

Les maquettes ne sont pas complètement implémentables en l'état

on n'a pas pas prévu d'avoir les logos des organisations
on n'a pas prévu d'afficher une liste des organisations / catalogues qui se met à jour automatiquement

Je proposais dans un premier temps que cette liste soit mise à jour à la main cf. https://github.com/etalab/catalogage-donnees/issues/358

Dans le même esprit, la FAQ est un moyen de faire une première implémentation basique qui répond aux besoins que j'ai listés, avant de travailler sur des améliorations comme celles que tu imagines dans ces maquettes.

Dans tous les cas l'implémentation la plus simple sera désormais systématiquement la première étape.

johanricher commented 2 years ago

L'idée d'une page FAQ sur le site est remplacée par une page dans le wiki sur Github.

J'ai activé le wiki et créé une page : https://github.com/etalab/catalogage-donnees/wiki/Documentation-%C3%A0-destination-des-utilisateurs.

Ce ticket pourra être fermé quand les sujets qui ont été jusqu'à présent identifiés ici seront traités sur cette page. Par la suite, on enrichira cette documentation avec les nouveaux éléments qu'on identifiera au fur et à mesure.

johanricher commented 2 years ago

J'ai créé une première version de la documentation à destination des utilisateurs.

@DaFrenchFrog peux-tu relire et faire éventuellement une deuxième passe ? Le but est de cocher les critères d'acceptation listés ci-dessus. Si tu penses qu'il manque des questions/réponses, n'hésite pas à les ajouter.

DaFrenchFrog commented 2 years ago

@johanricher J'ai apporté quelques modifications de détail mais la structure me semble bien. En revanche tu l'as mis dans une page intérieure. Est-ce que cela ne vaudrait pas le coup de mettre ce contenu directement à la racine ? Egalement des raccourcis vers les différentes questions pourrait être pertinent mais je ne sais pas comment le faire.

johanricher commented 2 years ago

Merci @DaFrenchFrog ! Le wiki est destiné à avoir différentes pages, mettre tout sur la home me paraît pas tenable.

Une table des matières est créée automatiquement dans la sidebar (à condition de mettre des headers bien hierarchisés).

johanricher commented 2 years ago

Pour finaliser, je vais ajouter un paragraphe qui décrit la possibilité d'importer un fichier et les conditons à respecter.

Une page de doc technique, qui décrit la procédure à suivre, sera rajoutée par @florimondmanca dans le dépot à partir de : https://github.com/etalab/catalogage-donnees/issues/456#issuecomment-1268631799

Volubyl commented 1 year ago

@johanricher est-ce qu'on peut fermer cette issue ?

johanricher commented 1 year ago

Je fermerai le ticket quand j'aurais rédigé cette partie : https://github.com/etalab/catalogage-donnees/wiki/Documentation-%C3%A0-destination-des-utilisateurs#comment-importer-un-catalogue-pr%C3%A9existant-sur-cataloguedatagouvfr-

etalab / catalogage-donnees