Framavox

Action 0 - Structuration de la documentation des plugins

Maïeul
Maïeul Public Seen by 25

La décision est de laisser les articles de plugins sur Contrib en réorganisant les rubriques (voir les actions suivantes). La possibilité d'intégrer la page plugin de Plugins SPIP à Contrib sera discutée plus tard.

Les plugins sont documentés de plusieurs manières:
- documentation techniques automatique pour certaines
- documentation utilisateur·trice·s qui peuvent être de différent profil:
- rédacteur
- webmestre
- intégrateur
- documentation factuelle : info sur l'état du plugin, la version, la compat

La question se pose de savoir
a) si toutes ces infos doivent être sur le même site, et si oui, est-ce Contrib ou Plugins SPIP
b) si il faut un site à part pour les elements factuels
c) comment gère-t-on les gens qui préfère documenter le plugin dans le depot svn/git lui-même

A ceci s'ajoute des metas documentations qui permettent d'expliquer comment arriver à un besoin en regroupant plusieurs plugins (ex pour les newsletters)

Maïeul

Maïeul March 29th, 2019 13:34

Deux sites différents (contrib.spip.net / plugins.spip.net)

Avantages

  • Habitudes
  • Ne pas considérer qu'un plugin est différent d'une autre contribution, ne pas hiérarchiser les valeurs

Inconvénients

  • Problème de synchronisation
  • Perte d'information lors de la recherche, car noyé dans un flot

Un seul site pour la doc des plugins (plugins.spip.net) séparés des autres contributions

Avantages :

- Un seul lieu à maintenir, plus de souci de synchronisation
- Plus proches des usages des autres CMS

## Inconvénients
- Perte d'habitude
- Problème de migration de la documentation, d'url rewriting et autre
- Séparation lors de la recherche, ce qui fait que des infos utiles dans d'autre articles pourrait ne plus être vu (?)
- Perte de la vérification éditoriale par le risque de tout automatiser (?)

RastaPopoulos

RastaPopoulos March 29th, 2019 14:25

Plus proches des usages des autres CMS

En partie faux : par ex Drupal qui est le deuxième plus gros CMS au monde avec des milliers de plugins, c'est juste un annuaire des projets, avec leur état, et une description. Et sur le côté, ya des liens possibles "Documentation", "Site de démo" etc, lorsqu'il y en a.

Documentation qui peut être sur le site des gens qui maintiennent (genre entreprise qui a son plugin bébé ailleurs etc) ou sur le site de doc de la communauté (comme nous pour Contrib). Mais ensuite quand on arrive sur la doc, on n'a pas de nouveau les infos automatiques techniques du plugin, on arrive sur la doc et basta.

Maïeul

Maïeul March 29th, 2019 14:32

Ah. Bon, admettons. Cela étant, il faut aussi tenir compte des usages de SPIP, et cela ne me paraît pas aberrant d'avoir l'info de compat à côté de la doc, surtout si on peut synchronisrr cela automatiquement.

RastaPopoulos

RastaPopoulos March 29th, 2019 14:36

Moi je ne vois (presque) pas l'intérêt si ya déjà cette info dans l'annuaire globale. On sait qu'on a UNE page pour chaque plugin qui a toutes les infos à jour, on sait que c'est là, et faut justement inciter les gens à trouver cette information là, mais surtout pas à 12 endroits à la fois.

Maïeul

Maïeul March 29th, 2019 14:39

bah ca fait faire un clic en moins aux gens qui cherchent via le moteur
de recherche de contrib, pour savoir si l'article qu'ils lisent peut
s'appliquer à leur cas. En outre, cela permet de gérer de filtres de
recherche.

Maïeul

Maïeul March 29th, 2019 14:44

Prend en cas d'exemple. Quelqu'un cherche à gérer des formulaires. Il tape "formulaire" sur contrib. Il tombe sur la doc de formidable. Maintenant, il veut savoir s'il peut installer ca chez lui. Bah il doit refaire un clic pour avoir l'info, si jamais il voit bien le lien qui lui indique "en suivant là, vous aurez les infos de compatibilités"....

Reciproquement il recherche sur plugins.spip.net. Bon, par chance il tombe sur formidable lorsqu'il cherche des infos sur les formulaires (pas évident !). Il a l'info de compatibilité, mais il faut qu'il trouve le lien de doc pour trouer la doc.

C'est peut être pour ca qu'un site unique, qui documente plugins et infos techniques pourrait être pertinent.

RastaPopoulos

RastaPopoulos March 29th, 2019 14:58

Non il ne doit pas refaire un clic forcément : j'ai indiqué sur la liste email (mais faut le redire là) que le seul lien technique nécessaire entre un article de Contrib et Plugins, c'est le préfixe du plugin.

Ensuite TOUTES les infos utiles sont déjà sur Plugins. Et alors
1) yora évidemment le lien vers la page complète mais
2) Plugins DOIT aussi fournir une API JSON pour accéder aux données, et on peut alors afficher seulement 1 ou 2 infos maximum (les plus pertinentes) sur les articles de Contrib qui ont le préfixe de renseigné. Une simple boucle DATA suffit, et du coup aucun doublonnement d'information, aucune synchronisation à maintenir, rien.

Maïeul

Maïeul March 29th, 2019 16:09

ok, on se placait pas sur le meme plan. Je me situait sur le plan de ce qui est fourni à l'utilisateur, tu te situais sur le plan de comment techniquement ont lui fourni ca. On est donc d'accord sur ce qui est fourni. Sur le comment techniquement ont fourni cela, c'est un autre problème.

RastaPopoulos

RastaPopoulos March 29th, 2019 16:16

D'accord sur ce qui est fourni : une partie. Sur les quelques infos à montrer oui. Pour ce qui est de la recherche, c'est une sujet dédié à mon avis, et je n'ai pas encore d'avis complet.

Mais là comme ça, je crois qu'actuellement ya jamais eu de direction claire là dessus, et du coup ça a incité les gens à faire n'importe quoi (enfin comme illes peuvent), et à chercher sur plusieurs sites. Donc là encore doublonnement de la fonctionnalité et deux choses à maintenir : faudrait qu'ils arrivent à trouver des fonctionnalités/plugins à plusieurs endroits à la fois, c'est un peu bizarre.

Si on cherche de l'éditorial, des explications, c'est sur Contrib, mais si on cherche une fonctionnalité, on devrait pouvoir trouver sur Plugins même sans corpus indexé monstrueux (titre, slogan, description, et filtrages type, tags, version doivent suffire à trouver rapidement : ergonomie de la recherche-filtrage).

Maïeul

Maïeul March 29th, 2019 16:20

on est d'accord. Sur la partie technique j'aurais des remarques àfaire, mais mettons nous d'accord sur l'editorial d'abord.

Maïeul

Maïeul March 29th, 2019 16:22

je me rend compte que ma phrase est ambigu. Nous sommes d'accord, en tout cas toi et moi, sur ce qu'on doit fournir en terme de contenu sur l'un et l'autre site. Encore qu'il y a la question du filtrage aussi sur rcontrib. Sur comment on fait techniquement entre les deux sites, j'aurai des remarques, mais accordons d'abord sur ce qu'on fait sur chaque site.

Lupinacci Eric

Lupinacci Eric March 29th, 2019 16:42

Plugins SPIP fournit déjà une API REST. C'est le plugin SVP API HTTP qui est installé depuis des lustres sur le site. Suite à une demande de Teddy j'avais créé ce plugin basé sur Serveur HTTP abstrait et qui fournit une API sur les collections plugin et paquet. Il faudrait que je revois le truc pour voir si il conviendrait votre utilisation mais si c'est pas le cas ça doit être sorcier de le faire évoluer.

Après j'attire votre attention sur le fait que le préfixe renvoie à un plugin alors que parfois les docs ne concernent qu'un paquet du plugin. Je reste convaincu aujourd'hui que laisser la documentation sur Contrib va nous demander des contorsions et des synchronisations compliquées voire non déterministe car il y aura toujours des cas non renseignés ou tordus alors qu'avec la bonne organisation sur Plugins en lien avec les catégories, les préfixes voire les paquets cette complexité serait atténuée (pas éliminée je pense).

Pour compléter on peut activer l'API ainsi:
https://plugins.spip.net/http.api/svp/plugins/boussole

Lupinacci Eric

Lupinacci Eric March 29th, 2019 17:17

Soit mais moi je ne suis pas d'accord. Ca serait bien qu'on ne soit pas les seuls à se prononcer d'ailleurs. Faudrait aussi intégrer ma proposition d'hier sur laquelle certains ont répondu dans le débat ici non?
On devrait peut-être inviter les gens à venir en parler ici, je ne suis pas sur que tous soient au courant.

RastaPopoulos

RastaPopoulos March 29th, 2019 17:28

Pour la manière de travail, je ne crois pas ce que soit bien de faire une consultation générale en faisant venir 12000 personnes ici. Le but d'un sous-groupe dans Loomio c'est d'avoir un groupe de travail, pas 50 personnes dans le même groupe, seulement celles qui vont travailler sur le long terme sur un sujet précis (et qui donc s'engagent à être dispo, à réunioner, répondre, etc).

Lupinacci Eric

Lupinacci Eric March 29th, 2019 17:31

Oui je suis d'accord mais là c'est un peu restreint comme cercle, nos avis divergent et d'autres ont émis des avis différents par mail qui ne sont pas retranscrits ici.

Maïeul

Maïeul March 29th, 2019 18:00

oui, il faut inviter, mais en expliquant explicitement ce que cela
implique en terme de charge de travail

Et du coup ... peut être se définir une méthode de travail (mais dans un
flux à part)

Lupinacci Eric

Lupinacci Eric March 29th, 2019 19:23

Je remets ici mon mail sur la réorganisation possible de Plugins SPIP comme annuaire étendu des plugins (incluant les documentations).

La première vue représente la page sommaire.
On retrouve presque tous les éléments actuels de la page sommaire du Plugins SPIP.
La liste des catégories est en navigation droite et on s'autorise deux niveaux (à confirmer plus tard).
https://pic.infini.fr/jWMEdEeD/vUUQhhUn.png

La deuxième vue représente la page d'un plugin au sens de Plugins SPIP actuel.
On voit par contre à droite les articles de doc qui sont regroupés dans un bloc de navigation.
Le bloc d'information d'un plugin est en partie droite et porte les informations qu'on retrouve aujourd'hui sur Contrib.
Un peu de couleur sur les versions SPIP en lien avec l'article des versions maintenues sur SPIP.net. Ca permet d'avertir sur l'intérêt aussi d'un plugin si celui-ci n'a que des versions "rouges". On pourrait aussi dans ce cas ajouter un bloc d'avertissement en bloc central.
Le contenu central est très similaire à celui de Plugins SPIP actuel.
https://pic.infini.fr/7fetLWjh/MGtOgy3X.png

La troisième vue représente celle d'un article de doc d'un plugin donné.
On retrouve en partie centrale le bloc du haut avec le nom et le slogan du plugin et dessous l'article et ses messages de forum.
A droite le bloc du plugin est toujours là et comporte aussi les zips et les liens vers l'autodoc, le source et la page de type annuaire (la précédente).

https://pic.infini.fr/5u5jPHJ5/0t2QSdZc.png

Les couleurs, le layout, le manque d'espace ne sont pas des features : c'est du manque de temps pour faire mieux, le but étant de montrer l'idée générale.
Il faut aussi imaginer les autres pages actuelles de Plugins SPIP (téléchargements, statistiques, valider paquet...) et de Contrib (contributeurs).

Lupinacci Eric

Lupinacci Eric April 12th, 2019 12:34

Cette action préliminaire est considérée comme close. La décision est de laisser les articles de plugins sur Contrib en réorganisant les rubriques (voir les actions suivantes). La possibilité d'intégrer la page plugin de Plugins SPIP à Contrib sera discutée plus tard.