Quel avenir pour la gestion de la doc des apps

Contribute Room Support & doc
1

Dans la page de présentation des apps (https://yunohost.org/#/apps), le lien de “Doc” d’une appli renvoie vers la page app_xxx.md du site (et en anglais en plus).
Par exemple pour minidlna, vers :
https://yunohost.org/#/app_minidlna_en
Et c’est vrai qu’elle fait un peu doublon avec celle-ci :
https://github.com/YunoHost-Apps/minidlna_ynh/blob/master/README.md

La “bonne” solution serait de n’utiliser que les pages de documentation “.md” des dépots _ynh de chaque appli. Comme ça, chaque packageur a en responsabilité de maintenir sa/ses pages de doc.

L’inconvénient, c’est que c’est plus lourd à maintenir parce qu’il faudrait forker chaque dépot si on veut modifier les pages de docs. Par exemple, si je peux corriger/compléter la page pour minidlna, je dois forker minidlna, juste pour une description.

Alors que pour l’instant, il suffit de forker yunohost/doc et de faire des PR pour modifier les pages.

2 Likes
2

@plumf a peut-être une idée précise de la question ?

3

@francoisa : Ça sort un peu du cadre du topic initial (app zerobin) mais c’est une discussion intéressante. On l’a déjà eu en meeting de contributeur, on est arrivé à la même conclusion que toi il me semble. Mais ça vaut le coup d’en rediscuter ne serait-ce que pour ce soit écrit quelque part et que les gens puissent réagir. Est-ce que c’est ok si je split les derniers messages vers un nouveau topic ?

Edit : bougé vers ce nouveau topic :wink:

1 Like
4

Oui, j’avais vu la digression du thread. Pas de souci pour le split. Zerobin était un exemple.

5

Ce sujet est en partie lié à la volonté (qui date depuis un moment maintenant…) d’afficher des infos supplémentaire avant l’install d’une app. Pas tout le README en entier mais des infos à avoir avant l’install :

  • screenshots et autre présentation de l’app
  • changelog eventuellement
  • limitations de l’intégration (par exemple c.f. le cas de Jitsi …)
  • contraintes ou autres “info techique” tel que estimation de la RAM requise, nécessité d’un domaine entier etc…

Idéalement le dernier point est à formaliser dans le manifest.json pour que Yunohost puisse intégrer ça de manière cool (genre faire le test que t’as bien assez de RAM / swap, etc …).

Les autres infos / messages / images pourraient se trouver dans un dossier doc/ dans l’app. La structure est à préciser en fonction de là où on veut vraiment aller avec ça. On peut faire des choses pour que ces fichiers soient inclus dans la doc de yunohost.org de façon automagique, mais effectivement, en terme de contribution, ça veut dire aller faire des pull requests sur chaque dépôt individuellement (que chaque mainteneur acceptera ou pas de merger… ).

Ou alors on peut imaginer l’inverse : un dépôt qui centralise la doc, et on la ré-inclu automagiquement comme là où il faut pour qu’elle soit dispo/montrée pendant l’install etc… Mais ça résous moins la question du “doublon partiel” entre la page de doc et le README

2 Likes
6

Désolé si c’est hors sujet mais je trouve la discussion intéressante.
Puisque chaque application utilise un repo Github/Gitlab, pourquoi ne pas avoir le wiki de l’application ? On parle de documentation, donc pour moi il y a la logique d’avoir un wiki, et chaque repo se voit attribuer un repo dédié.

7

Je signale aussi que la première info qui est donnée sur une possible documentation est celle qui apparait sur la page doc des apps ici :
https://yunohost.org/#/apps

Chaque “app” présente 2 liens boutons :

  • Code : qui renvoie vers la page d’accueil du github, plutôt familière pour les admin/dev/sys , mais pas pour tous les admins de Yunohost.
  • Doc : qui inviterait à quelque chose de plus simple et plus convivial.

D’ailleurs, pourquoi le lien Doc pointe-t-il vers la page forcément en anglais “_en.md” par défaut au lieu de app_APPLICATION qui est un lien plus commun et valable selon la langue du navigateur ?
Pourrait-on le corriger ?

Je soumettrai bien le lien :

<a href="#/app_{app_id}" target="_BLANK" type="button" class="btn btn-default col-sm-4"><span class="glyphicon glyphicon-book" aria-hidden="true"></span> Doc</a>

au lieu de :

<a href="#/app_{app_id}_en" target="_BLANK" type="button" class="btn btn-default col-sm-4"><span class="glyphicon glyphicon-book" aria-hidden="true"></span> Doc</a>

Personnellement, je pense qu’il faut les 2.

Sans doute même que la forme est à retravailler, mais il faudrait choisir un lieu et un fonctionnement pour qu’il n’y ait pas de doublon d’infos, trop lourdes à maintenir.

Les packageurs doivent adresser des infos pour les admins, tandis que la page de doc s’adresse à ceux qui veulent en savoir plus sur l’application et doit rester permanente :

Page de doc (dans yunohost)

  • Logo + Nom
  • Niveau d’intégration + lien installation
  • Présentation de l’application
  • Captures d’écran
  • lien vers site officiel
  • lien vers documentation
  • lien vers dépôt de l’app
  • lien vers remontée de bug

Les infos comme les limitations, la configuration, les mises à jour relèvent du packageur et qui sont amenés à évoluer, devraient se retrouver dans les README du dépot.

Page README.md

  • Nom Appli
  • Site officiel
  • Lien vers page de doc
  • version fournie
  • Configurations
  • Administration

Dans le dépot exemple : https://github.com/YunoHost/example_ynh
les parties screenshot, demo me sembleraient superflues.
et seule la version anglaise du readme (pour admin) serait utile, alors que les pages de doc pourraient être traduites en plusieurs langues facilement par des traducteurs en masse.

Dans cette page : https://yunohost.org/#/doc_writing_guide
Je pense que les infos des points 5, 6 et 7 relèvent donc du packageur.

8

Anéfé c’est un bug :+1:

9

Ce qui n’est clair pour moi, c’est pourquoi la présentation de la liste des apps est différente sur yunohost.org et sur https://mondomain.tld/yunohost/admin/#/apps/install

Sur Yunohost.org, on a 2 boutons :

Et sur l’interface perso de mondomaine.tld/yunohost/admin on a :

  • Code : vers la page Github
  • Readme : vers le Readme du github (qui affiche en fait la même chose que le lien du haut)

S%C3%A9lection_163
S%C3%A9lection_1631240×533 57.1 KB

Ce n’est pas un peu contradictoire ? Il n’y aurait pas moyen d’harmoniser tout ça ?

Comme argumenté plus haut, je proposerai bien d’avoir :

  • Code : page github qui ne concerne que les paramètres d’install dédié aux admin, restrictions…
  • Doc : page “alléchante”, descriptive de présentation de l’application.

Dans mon cas, je peux produire des fiches de doc, car je connais les logiciels, je les ai utilisés et je peux expliquer ce qu’ils font dans les grandes lignes, trouver les logos, la documentation officielle…
Mais ensuite, les restrictions, conditions liées à l’app peuvent varier dans le Readme du github, ce qui est du ressort du packageur et peut évoluer au gré des PR et des Mises à jour. Alors que la fiche de doc ne changera quasiment pas.

Pour moi, les screenshots relèvent de la page “doc” mais pas du dépot.

Mais c’est juste mon point de vue…

1 Like
10

(On parlera de l’aspect graphique qui est compliqué à gérer car les lib disponibles sont différentes mais c’est pas le sujet je crois :stuck_out_tongue: )

Oui un peu, mais pour expliquer : historiquement les choses viennent un peu au fur et à mesure qu’on les fait et il y a douzmille fronts sur lesquels travailler, donc clairement des trucs ne sont pas forcéments harmonisés (ou en tout cas il y a un travail d’harmonistation constant …) … Rien n’est figé, tout est sujet à discussion :stuck_out_tongue:

Bref, tes critiques sont justifiées. Si je me souviens bien, il me semble que la dernière fois que l’on a vraiment refait la page YunoHost app store | Application Catalog,

  • il y avait encore très peu d’apps documentées sur la doc yunohost.org, mais toute de même quelques unes … et on s’était dit que c’était l’occaz d’essayer d’encourager les gens à remplir ces pages
  • on souhaitait éviter d’envoyer les gens vers le README car peut-être plus ‘technique’, moins uniformes à l’époque, et moins facile d’y contribuer … ça emène les gens sur un autre site, et puis le README est accessible dans ‘Code’.
  • mais bref la conclusion est celle que tu dis, il y a au moins deux niveau de doc:
    • le README contient des infos techniques qu’il serait pertinent de formaliser et présenter à l’admin juste avant l’install
    • la page de doc “alléchante” avec différentes info de prises en main

Perso je dirais naïvement qu’on devrait:

  • à terme, faire disparaître le bouton ‘Readme’ et ‘Doc’ de la liste d’apps (celle de l’admin et celle de la doc’)
  • dans la webadmin: montrer le README (ou un truc qui contient des infos similaires, plus standardisé) avant / pendant la procédure d’install
  • dans la webadmin: mettre au moins un bouton vers la page de doc de chaque app pour chaque app install … Peut-être aussi dans le portail utilisateur (SSO), à voir
  • dans la doc: mettre en avant les pages de doc des apps par d’autres moyens (par exemple, un bouton “Doc des apps” ici : YunoHost • index )

Peut-être qu’on penses à deux choses différentes :wink: Il peut y’avoir des screenshots pour des explications détaillées sur des aspects précis (par exemple partager un fichier sous nextcloud ou que sais-je) et des screenshots généraux pour montrer à quoi ressemble l’app ‘en gros’ (parallèle avec ce qu’il se passe sur l’app store de Google Play ou autre…)

1 Like
11

J’ai fait des pages de doc fr et en sur la plupart des applis que je connaissais à partir du template https://yunohost.org/#/app_writing_guide de @Plumf
J’ai repéré encore un paquet de pages qui n’ont pas de doc, mais je connais moins ces softs.

Est-ce qu’il faut plutôt :

  • compléter ces pages manquantes avec des infos même sommaires avec des liens vers les pages de code ?
  • ajouter des screenshots sur les pages de doc existantes (il y en a pas mal dans les README) ?
  • autre doc “utilisateur” à compléter/corriger ?
12

J’ai remarqué que dans la liste des apps présentes ici (j’imagine que la liste de références des apps de Yunohost), certaines apps n’étaient pas hébergées sur le dépot Yunohost-Apps mais sur d’autres dépots personnels comme :

Je suis en train de préparer une petite interface web pour lister facilement toutes docs qui manquent et tous les logos en SVG à récupérer en proposant un formulaire simple :

  • url officiel
  • url Documentation
  • url Démonstration
  • description en fr
  • description en anglais

Je vous la soumets dès qu’elle est pleinement fonctionnelle. C’est juste pour simplifier et accélérer les contributions sur ces pages manquantes.

J’ai tout de même noté 307 fiches de docs. Et il y a moins de 100 applis documentées.

De quelle liste faut-il partir pour récupérer la liste des applis disponibles dans l’interface d’ajout des apps ?

1 Like
13

A mon avis c’est pas trop la peine de chercher à documenter les X centaines d’app …? Le fichier apps.json est plus un index que “le vrai catalogue d’app installable”. D’ailleurs dans celles listées dans apps.json, on sait pertinemment que beaucoup d’entre elles ne seront plus jamais installables ou pertinentes (par exemple, owncloud mais il y en a d’autres)

Les apps réellement installables sont les apps étiquettées “working” et parmis celles-ci, les “decent quality” sont celles avec une niveau d’au moins 4. Du coup il en reste quelque chose comme 120 (c.f. aussi ce dashboard et celui-ci)

C’est une recommendation (car ça aide si on veut que la communauté prenne le relai etc) mais dans l’absolu non … D’ailleurs il y a normalement un projet de migrer ailleurs que sur github…

14

Ouahou, joli le dashboard ! J’aime beaucoup le grahique avec la progression des applis “working, notworking…”
Tartiflette, c’est du Flask, jinja… J’adore ce framework que je découvre depuis quelques semaines. C’est une tuerie.

Bon, donc pas besoin de gaspiller de l’énergie à documenter des trucs qui ne serviront plus… On va déjà regarder les logos manquants.

Par rapport ce que tu avais expliqué plus haut, je ne sais plus trop vers quoi me tourner et que proposer pour améliorer de la doc “utilisateur” pour l’instant…
J’étais un peu enthousiaste à l’idée de rédiger des fiches manquantes, mais là, je ne sais plus trop quoi faire.

1 Like