Remplacer Code par Search (et laisser Search dispo pour autre chose)

Équipes documentation
#1

Hello, une petite proposition qui me semble relever de l’organisation de la documentation et du retrouvage de contenus dans l’immensité de la galaxie.

Maintenant qu’on a Search motorisé par Sourcegraph, qui est vraiment très très bien (encore merci), il me semble que Code.spip n’apporte plus grand chose d’intéressant et devrait être totalement supprimé. En effet Sourcegraph :

  • s’occupe intégralement de « code »
  • permet de rechercher en fulltext dans TOUT le code, et ce aussi bien du core que de tous les plugins du monde
  • donne accès au PHPDoc
  • et cela pour TOUTES les branches à la fois, et donc absolument pas besoin de maintenir plusieurs instance suivant les versions de SPIP etc ! (comme Programmer)

Quand bien même ça ne couvrirait pas 100% de ce que permettait Code.spip, ça en couvre laaaargement assez (et des choses en plus) pour ne pas se fader la maintenance d’un site en plus inutilement.

Si jamais on est d’accord pour n’en maintenir qu’un, alors mon avis serait que Sourcegraph remplace vraiment et passe sur le domaine code.spip.net. En effet : il ne s’occupe QUE du code, et non pas de la recherche en général dans tous les contenus.

Cela laisserait alors le domaine search.spip.net (qui dans un premier temps pourrait rediriger vers code.spip.net) pour à terme peut-être avoir un portail de recherche qui permettrait de lancer une recherche dans TOUS les sites de la galaxie à la fois (par exemple avec un Manticore central qui indexerait spip.net + le blog + contrib…).

#2

je suis assez d’accord. D’autant que la recherche dans code.spip.net est ergonomiquement désastreuse.

#3

Peut-être oui mais pour l’instant il est facile de naviguer dans Code alors que pour search il va falloir apprendre comment l’utiliser. Donc on ne peut pas le faire sans expliquer comment passer de l’un à l’autre.

Et puis quand on navigue dans un plugin de code, on voit d’emblée la liste des api par exemple. On va perdre cette possibilité qui est quand la plus intéressante à mon avis. On ne va pas sur Code pour faire un search non ?

#4

bah si moi j’allais intégralement sur Code que pour chercher tel ou tel nom de fonction et avoir son PHPDoc, comment ça s’utilise (et la recherche était effectivement horrible).

Si je veux chercher la cohérence entre une série de fonctionnalité, pour moi c’est à la doc de le faire (par ex sur Programmer pour ce qui concerne les devs). C’est ce qui est fait dans Symfony quand ils documentent des modules fournissant telle API, par ex la doc de httpfoundation ou du routeur d’url, etc.

Comme je le disais, même si ok ça ne se superpose pas à 100%, Searchgraph apporte 99% des mêmes choses + des choses en plus (toutes les branches, tous les plugins, la méga rapidité, le survol sur n’importe quel élément, etc, etc). Donc on y gagne bien plus qu’on y perd, et à la fin, je ne trouve pas intéressant de maintenir toute une infrastructure et un domaine juste pour conserver les 1% qu’on y perd (et que pas sûr que beaucoup utilisent). Pour moi Searchgraph s’occupe intégralement que de code et remplace avec beaucoup d’avantages (et si peu d’inconvénients) pour la majorité des recherches/usages qu’on faisait sur l’ancien Code, donc devrait être sur le domaine Code à place.

#5

Oui mais là tu parles de spip uniquement qui a sa documentation de programmation. Mais les plugins n’ont pas l’équivalent et là on le perdrait.

#6

+1 pour ne garder que SpipSearch (et son nom de domaine actuel ne me dérange pas, l’intérêt de le changer est tout de même minime, je trouve) s’il ne faut en garder qu’un. Et l’utiliser est quand même assez simple … ça ressemble à google …

En tant que dev, je ne vois pas vraiment le problème de conserver les 2 sites, surtout que phpdocumentor génère des pages statiques qui ne pèsent pas bien lourd en volume et en consommation au moment de la production de ces pages … la recherche sur ces pages est un peu cheap, mais c’est surtout parce que notre PHPDoc est pas tip top … Mais en général, c’est pas pour ça qu’on expose une API. C’est sensé se lire comme un document cohérent…

#7

@eric_tonton en gros si je comprend bien, ce que tu regretterait de perde sur code.spip.net c’est la navigation dans la liste des fonctions d’un plugin ? ou bien c’est autre choses ?

#8

En gros oui c’est ça.

Déjà je pense que @rastapopoulos ne parle que du phpdoc de spip : là je suis d’accord, à partir du moment où on a programmer on pourrait imaginer de ne plus générer ces pages. Néanmoins, il faudrait s’assurer que toutes les api de spip sont documentées, et là, on en revient à l’équipe Architecture et à la notion d’api.

Ensuite, il y a les plugins : là aucune documentation de dev n’est disponible (sauf sur mes plugins qui embarquent un guide de conception). Le site permet d’avoir une vue rapide des fonctions, balises et autres qu’offrent le plugin et je trouve ça utile même si je vais pas y aller tous les jours. En tout cas, cela sera perdu sans alternative.

Après c’est pas le combat le plus important non plus.

#9

Bé les plugins : c’est dans Contrib leur doc, donc à eux de faire une doc adéquat de ce qu’ils considèrent comme étant public. (Et c’est prévu dans l’évolution de mieux avoir plusieurs articles pour un même plugin et mieux pouvoir les distinguer quand ya besoin)

#10

Oui c’est une bonne idée mais elle prendre du temps voire elle ne verra jamais le jour. Mais si franchement vous trouvez ça mieux de tout mettre au rebut je m’y ferais.
Par contre, on pourrait éventuellement ajouter un type d’article « dev » (ou un nom plus adéquat) pour les articles de type programmer non ?

#11

L’intérêt c’est d’avoir le moins de sites différents possibles, ce n’est pas qu’une question de maintenance admin sys (même si ça fait un truc en moins quand même). Pour le grand public, la profusion de mille sites et ne pas savoir où chercher quoi, surtout quand c’est ajouté dans le bandeau commun de galaxie en haut, ça perd lesgens.

Tout comme on essaye de fusionner Contrib+Plugins pour ne garder qu’un qui parle du sujet « plugins », je trouve donc bien ergonomiquement/UXement de ne garder qu’un seul site dont le sujet est « la doc de code automatisé ».

Sinon je parle autant du core que des plugins (dist et pas dist) : Searchgraph est encore bien mieux que l’actuel Code car il donne accès à vraiment 100% de la forge, avec une recherche transversale (permettant de faire des liens) + ça gère toutes les branches de tous les plugins. Donc même pour les plugins ça reste mieux de mon point de vue. Au pire quand on veut récup que les trucs tagués « @api » ou que les balises, la recherche fulltext est tellement rapide que chercher ces termes renvoient immédiatement ce qu’il faut et on peut restreindre à tel dépôt. Sourcegraph

#12

Perso ça me va, je n’ai que très peu d’usage de code.spip.net.

#13

Pas d’objection non plus.
Pour info phpdocumentor ne fonctionne pas très bien avec le code de SPIP car il n’utilise pas de namespaces / classes…

#14

@rastapopoulos tu me perds là … tu dis tout et son contraire, je n’y comprends plus rien …

« se fader la maintenance » : bah tu le faisais déjà pas, c’est semi-automatique. Donc, c’était déjà pas un fardeau pour toi.

Certes, on accède à la phpdoc via search, mais c’est déjà possible sur la plate-forme gitlab ET sur son poste, soit parce qu’on a cloner/télécharger, unitairement, ou via le script gitea_mirror. C’est un outl de recherche, pas de doc.
Mais phpdocumentor à pour vocation d’afficher des pages html "organisées basées sur la PHPDoc : code est un site de doc. technique certes, mais de doc. (et je rappelle : son « coût » de maintenance est mineure.)

T’as au moins 2 personnes qui te disent « pas d’accord pour n’en maintenir qu’un parce que c’est pas gênant de garder les deux ». 2 personnes qui sont « devs » et qui se sentent concernés par la doc technique.

Plutôt que de se débarrasser du site « code », il me semble qu’on y gagnerait à améliorer la matière qui l’alimente . Certes, c’est pas le même boulot… Mais ça profitera à plus de monde, et même à « search » …

Ensuite tu dis « avoir le moins de sites différents possibles » et que ce n’est plus une question de maintenance … bon … mais tu fais appel au « grand public » alors que ce sont avant des outils pour les « devs » … là tu me perds … le grand-public, les gens, les non-techniques … n’ont aucun intérêt ni pour « search », ni pour « code » … vu que c’est technique justement …

Enfin, tu parle de « ergonomiquement/UXement » … mais les « devs » ont besoin de « DXement » si je puis dire…

Du coup, je trouve que tes arguments ne tiennent pas trop la route.

Si on résume : Tu veux enlever le site « code » de la boussole. C’est peut-être ça le vrai sujet, non ?

#15

améliorer la matière qui l’alimente

:wink:

#16

Je parle évidemment du public de devs non happy few (les 5-10 qui sont là depuis 20 ans ou plus et qui connaissent tout par cœur, sur quel morceau de code chercher, sur quel site chercher quelle chose, etc) qui cherchent à faire des choses avec SPIP (ou ses plugins), et dont le but est (un peu) d’augmenter le nombre.

C’est (très) régulier que les nouvelles personnes qui arrivent dans l’univers SPIP fassent la remarque (le reproche) que la galaxie non centralisée est foisonnante et qu’on ne sait pas où chercher quoi dans la (LES) doc.

Ce pourquoi c’est parfaitement pour ce « grand public » (de devs/intégrateurices) qu’il faut aussi limiter le nombre de sites faisant « à peu près la même chose mais un peu différent ». Un seul site pour les plugins et non plus deux, un site pour le code auto, etc, autant que faire se peut (et non on peut pas chercher la forge entière sur gitlab comme ça, et non encore moins en local non plus à moins de télécharger ET maintenir à jour un monstrueux miroir total chacun en local)

Si on garde l’ancien code.spip car il ne gène pas en maintenance, alors oui pour moi faudrait l’enlever de la boussole (pour ne pas perdre les gens), mais en gardant Code : ce domaine est plus vieux et plus connu (et plus dans les favoris etc) que le nouveau, et donc pour moi ce nouveau Sourcegraph qui permet de naviguer/chercher/lire dans encore plus de code qu’avant, devrait donc être the nouveau « code.spip ». Et l’ancien serait dans un nouveau domaine plus dans la boussole (phpdoc.spip par ex).

#17

Quand je te lis, le coté « géométrie variable » des termes que tu emploies OU des définitions que tu leurs donne peut faire mal à la tête, mais peut aussi donner le sourire :slight_smile:

L’an passé, les devs ne comptaient pas, voire n’existaient qu’à condition qu’ils soient payés par des clients. Maintenant, il y a des dev happy few et et devs non happy few … qui deviennent par la même occasion le grand public, qui était non-technique il y encore quelques mois.

Si tu souhaites qu’on te comprennes, penses à fournir les mises à jour de ton dictionnaire personnel, s’il te plait. On aura moins mal à la tête :wink:

Et je note qu’on est passé de « 3/4 max à maintenir le code » à "5-10 qui sont là depuis 20 ans… Des gens commencent à exister à tes yeux, c’est cool :+1:

pour le « et plus », bah y a plus que moi :smiley:

Derniers points :

« à peu près la même chose mais un peu différent » c’est une fois de plus totalement faux. « code » et « search » sont 2 fonctions très différentes, l’un est un site de doc, l’autre un moteur de recherche… c’est pas du tout identique à peu de chose près…

« connaissent tout par cœur, sur quel morceau de code chercher, sur quel site chercher quelle chose, etc » bé non… c’est pas possible. SPIP c’est plus de 200 000 lignes de code dont près de 45 000 lignes de commentaires (données de langues exclues). C’est impossible de tout connaitre par coeur et j’ai pas compté les plugins-dist. Ça s’est une exagération de ta part, c’est comme « la profusion de mille sites » … et je crois que ça, pour le coup, c’est rhétorique…

« encore moins en local non plus à moins de télécharger ET maintenir à jour un monstrueux miroir total chacun en local » bah si, j’ai lu plusieurs témoignages récemment sur ce forum de cette pratique, grâce au script « gitea_mirror » (et je savais pas que ça existait …) pratique qui remonte à subversion, maintenue au passage à gitea via le script, car personne n’a pensé à dire, ou ne savait, qu’il y a avait une recherche de code globale qui marchait pas trop mal et qu a disparu à l’arrivée de gitlab, d’où l’arrivée de sourcegraph …

Bref, les devs deviennent « grands publics » quand tu veux récupérer un nom de domaine bien référencé pour l’outil que tu préfères utiliser , c’est ça ? Si c’est le cas, il y aura 2 lignes de commentaires à supprimer dans spip/spip, répertoire prive/formulaire, je te laisse chercher avec l’outil que tu veux :wink:

#18

Blablabla tu joues sur les mots pour ne surtout pas parler du fond. Franchement je pensais (vraiment) pas que cette modeste proposition aboutirait à devoir détailler à ce point…

Dans la phrase

Pour le grand public, la profusion de mille sites et ne pas savoir où chercher quoi, surtout quand c’est ajouté dans le bandeau commun de galaxie en haut, ça perd lesgens.

Bah oui ça parle à la base de TOUT le monde, dev et pas dev, donc bien encore plus grand public que « le grand public parmi les devs ». Le fait de multiplier le nombre de sites (ayant chacun un champ de recherche), ça aboutit à ce que tout le monde (sauf quelques personnes, on en a rien à foutre du branlage de mouche que ce soit 4, ou 5 ou 10, tu te perds dans tes ironies et c’est toi qui rend un peu tout confus) soit un peu perdu sur où chercher quoi.

Donc de base limiter le nombre de sites, c’est une bonne chose ergonomiquement. Ça parait vraiment fou de baratiner sur ce point. La boussole ne change pas magiquement suivant le profil de la personne sur la chaise en face, on a tous la même.

Ensuite à l’intérieur des devs bah oui il y a les quelques personnes là depuis le néolithique (ça rime avec rhétorique), et la majorité des users-devs (qui utilisent SPIP pour leurs devs), qu’illes soient là depuis un peu ou pas du tout longtemps. Et pour ce public là « à l’intérieur des devs », il y a donc bien aussi une distinction avec « le grand public des devs » (pas les N néandertalien⋅nes) et dont les nouvelles et même parfois des plus vieilles, font régulièrement la remarque que même à l’intérieur de la doc de dev on sait pas trop où chercher.

Autrement dit, pour les devs ça confusionne, et pour les non devs ça confusionne aussi car même quand un site ne leur est pas destiné, on s’en fout car c’est quand même là dans la même liste, et avec un champ de recherche aussi (et avoir ça en plus de Code sur « search » n’incite pas à penser que ça va être que pour le code = déceptif pour les non devs une fois dessus).

Quand au « c’est pas pareil », merci, je l’ai un peu dit dès le départ… Mais ce qui importe n’est pas ce que ça produit, c’est quelle utilisation en est faite. Et je mets ma main à couper (ça aussi c’est rhétorique ?) que la majorité des recherches de code.spip servent (servaient) à trouver les arguments et la description en français de ces arguments pour telle ou telle fonction. Ce que remplit parfaitement Sourcegraph… en beaucoup plus rapide, plus complet (multi branches donc en pouvant voir l’évolution des arguments etc), donc en beaucoup mieux. Le reste me parait vraiment minoritaire (combien de clics sur les plugins dans code.spip ? 2 par an à mon avis), et donc pas assez important pour que dans la balance ça vaille le coup de confusionner avec plusieurs sites automatisés sur le code dans la boussole.

Bref je te trouve très acrimonieux, et bon, on peut laisser comme ça aussi… c’était juste une modeste proposition pour dès que c’est possible arriver à réduire chaque fois un peu plus le nombre de sites différents dans la galaxie, pour ergonomiquement de moins en moins perdre les gens. Pas si important.

#19

les tiens, seulement les tiens

Bah si, mais je veux bien recommencer :

« code » eet « search », c’est une affaire de « devs », de DX, et certain·e·s trouvent que les 2 sont utiles, les autres ne s’en servent pas. Le fond est là. Le reste, c’est tes arguments fallacieux…

Le fond, c’est que tu veux récupérer un nom de domaine pour un outil que t’aimes bien, réduire le nombre de sites techniques dans la boussole, en dépit de tes propres arguments à peu près valables d’ailleurs : « ce domaine est plus vieux et plus connu (et plus dans les favoris etc » mais au cul les redirections avec ta proposition …

Le fond, c’est que tu n’écoutes pas les devs mais que tu parles en leur nom. Enfin … quand t’en as besoin, quoi…

« pour les devs ça confusionne » : sur le fond, non. Les devs cliquent et comprennent où ils arrivent. Tu les infantilises là. Et "les non devs ça confusionne aussi " : sur le fond, non plus. Ils n’y vont pas, ça ne les intéressent pas…

Sinon, oui « limiter le nombre de sites, c’est une bonne chose ergonomiquement. ». D’ailleurs, on l’a déjà fait, mais avec des sites qui n’avaient plus d’activité (party), ou qui devenait inutile car redondant (sedna), et d’autres, j’ai perdu le compte… J’ai même évoqué la fusion du blog dans spip.net à une époque…

Et sinon, au final, le seul truc qui te dérange, c’est qu’il y une zone de recherche dans « code ». Et si on l’enlèves, tu dormiras mieux ?

Maintenant, si tu n’en à « rien à foutre » du nombre de personnes, ceci-celà, bah arrête de balancer des chiffres approximatifs pour faire genre, parce que tout ce qu’on voit, c’est que tu bullshites tout pour pas cher.

Et stop avec « le néolithique » et autres allusions sur l’âge de certain·e·s, c’est offensant, c’est de l’âgisme. De la part d’un mec qui prône l’inclusivité, ça la fout mal.

#20

(pour celleux plus récents, je suis sur les listes SPIP depuis 2003, donc c’est en premier lieu de moi et des « vieilles personnes » de la même époque que je parle, et monsieur le sait très bien donc ça n’a aucun sens, à part faire le vieil aigri)

tu n’écoutes pas les devs mais que tu parles en leur nom

Dit le mec qui ne parle que de son expérience de méga-super-avancé-dev-qui-connait-spip-depuis-25-ans mais qui n’entend pas les remarques forts régulières (sur les listes/forums) sur le fait que les nouvelles (devs/intégrateurices) sont souvent perdues d’où chercher les choses.

Le fond, c’est que tu veux récupérer un nom de domaine pour un outil que t’aimes bien

Le fond c’est que dès que je dis un truc tu en fais une affaire personnelle et tu transformes ça en une sorte de lubie individualisante.

Alors qu’en l’occurrence (et ça vaut pour d’autres sujets) : j’en ai strictement rien à carrer de « récupérer un nom de domaine » et je n’aime pas tel ou tel outil : moi je sais me débrouiller et trouver tout car justement je connais depuis longtemps et je ne vais pas être perdu. Je parle donc uniquement d’un point de vue ergonomie donc d’accueil des autres gens qui connaissent moins, et que je lis sur les forums, la manière donc illes trouvent ou pas les choses facilement, et j’en prend note pour proposer des simplifications (+ le fait que sourcegraph remplit 99% des utilisations pour lesquels on allait auparavant sur autodoc, même les ceusses qui connaissent bien, c’est même marcimat qui m’a dit l’autre jour mais pourquoi tu vas encore sur ce site pour la doc de telle fonction, tu trouveras sur search bien plus facilement : true fact).