Documentation à destination des utilisateurs

[johanricher]

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 :

• Comment contacter les personnes responsables du projet ? (cf. ETQ utilisateur je peux contacter l'équipe #370)
• Quelle est la liste des organisations / catalogues sur l'instance ? (cf. Liste publique des organisations #358)
• Comment s'enregistrer (explications Datapass) ? (cf. Enregistrement et connexion #124)
• Comment créer une organisation (process de demande et validation avant la création) ? (cf. Création d'une organisation #334)
• Comment importer un catalogue préexistant ? (cf. Import de catalogue #343)

Implémentation

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

[DaFrenchFrog]

@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]

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. #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]

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]

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]

@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]

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]

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 : #456 (comment)

[Volubyl]

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

[johanricher]

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-