Framavox

Action 0 - Structuration de la documentation des plugins

M 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)

M

Maïeul Fri 29 Mar 2019 1:34PM

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 (?)

R

RastaPopoulos Fri 29 Mar 2019 2:25PM

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.

M

Maïeul Fri 29 Mar 2019 2:32PM

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.

R

RastaPopoulos Fri 29 Mar 2019 2:36PM

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.

M

Maïeul Fri 29 Mar 2019 2:39PM

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.

M

Maïeul Fri 29 Mar 2019 2:44PM

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.

R

RastaPopoulos Fri 29 Mar 2019 2:58PM

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.

M

Maïeul Fri 29 Mar 2019 4:09PM

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.

R

RastaPopoulos Fri 29 Mar 2019 4:16PM

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).

M

Maïeul Fri 29 Mar 2019 4:20PM

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

Load More