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.
+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…
@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 ?
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.
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)
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 ?
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
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…
@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 ?
améliorer la matière qui l’alimente
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).
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 
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
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 
pour le « et plus », bah y a plus que moi 
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
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.
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.
(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).
Aie ça va faire mal
Je pense que votre débat part dans une issue parce que je ne suis pas sur qu’on ait posé la bonne question au début du fil. Elle est trop fermée alors que le sujet est plus large.
Moi j’utilise Code.spip sur les plugins principalement, pas le spip car je préfère aller sur Programmer quand l’explication existe - mais elle n’existe pas toujours - et dans le code sinon. Mon utilisation c’est la compréhension de l’API dans son ensemble ce qui me parait pas possible vue de ma fenêtre avec Search qui est impressionnant mais pas forcément intuitif.
Pour les plugins, je l’utilise :
- Pour avoir une vue globale du plugin (api, balises, critères, etc)
- Vérifier le phpdoc : complétude, erreurs, etc. Et ça seul une génération de phpdoc peut le fournir. Alors y a peut-être une autre façon de faire avec une installation local ou distante comme un service ?
Donc quoi qu’on décide, Search ne remplace pas Code.spip.
Maintenant, on peut s’adapter si ça permet à certains de se libérer du temps.
Après, on voit aussi que Programmer n’est pas complet au niveau des api et que le code ou le phpdoc est utile. Il ne faut donc pas supprimer sans faire l’effort de complétude où qu’il soit. C’est en sens que je dis que la question initiale n’est pas la bonne.
On a de la chance on est au bon endroit pour en discuter
Désolé je n’ai pas tout lu vos commentaires… je vais juste ajouter quelques remarques sur pourquoi je trouve code.spip.net peu pertinent maintenant. Et je suis d’accord avec Eric pour dire que Search ne le remplace pas fondamentalement.
-
avant (une version antérieure de PhpDocumentor que j’avais beaucoup adaptée), on avait une page pour les balises, boucles, critères, etc. qui était extraite, et ça c’était sympa, très spipiennement utile. Ce n’est plus le cas avec les nouvelles versions : je n’ai vraiment pas eu le courage / le temps de refaire ça : l’extraction automatique c’est bien, mais ça ne remplace pas toujours une documentation plus rédigée d’exemples à la mano.
-
maintenant les IDE sont puissants, vraiment… tu ouvres ton dépot git dedans, tu as toutes les infobulles qui montre la définition des fonctions, t’aide à l’auto-complétion… détecte mieux les incohérences que toi-même… C’est incomparable avec il y a quelques années auparavant.
-
les projets git se sont assez structurés et reposent très souvent sur une documentation uniquement intégrée dans le dépot git : le readme et un répertoire docs/ , qui est parfois exporté en site statique. Ça permet de créer des PR pour la doc, de la mettre à jour en même temps que les modifications de code. Si quelque chose devait se structurer à long terme, ça me semble le plus logique. À ce moment là, code.spip ou Contrib pourrait pourquoi pas récupérer ou accéder à ces documentations là.
-
pour les API, il me semble qu’on se fourvoie un peu en pensant essentiellement au code actuel de SPIP. C’est plus simple de considérer en programmation objet, que les classes interfaces, et les fonctions à visibilité publiques sont des APIs… et le reste… bah simplement non. Et les IDE s’en accommodent bien.
Dans SPIP actuellement tout est plutôt mélangé et des fonctions internes sous prétexte qu’elles ont été utilisées quelque part (simplement parce que par défaut tout est utilisable publiquement) sont devenues considérées comme des entrées possibles, et c’est aussi un problème qui peut limiter les évolutions.
Bref, j’espère que je ne digresse pas.
1 « J'aime »
Oui absolument, on en avait discuté quand tu avais mis à jour le nouveau code.spip pour lequel j’avais déploré les pertes que tu as citées. Mais c’est vrai que le spécifique c’est lourd à gérer.
Oui c’est peut-être une bonne réponse. De mon coté j’ai mis dans mes derniers plugins de type « API pour quelque chose » un guide de conception qui couvre les besoins cités mais qui est aussi assez lourd à maintenir. Maintenant je peux attester que pour revenir une fois par an sur les plugins, c’est d’une efficacité redoutable.
Il serait intéressant d’avoir un fil de discussion sur ce sujet en tout cas.
Là on diverge. La programmation objet ne peut pas être la seule à proposer une logique d’API car c’est trop technique. comme approche Il nous faut documenter nos api a minima pour dire que tout ce qui n’est pas documenté n’en est pas.
On a eu le cas avec extraire_trads() en spip 5.0. Le fait que l’on réduise la liste des api ne me pose pas de souci si on l’établit clairement et que cela a du sens au niveau de l’utilisateur.
C’est pourquoi que je pense que pour SPIP 5.0 c’est un chantier prioritaire que de définir nos api qu’elles soient en POO ou pas.
Bé oui oui, c’est exactement ce que j’ai dit… depuis le tout début 
C’est-à-dire que :
- j’ai bien dit dès le tout premier message que ça faisait pas 100% pareil
- les IDE et/ou Sourcegraph additionnés permettent néanmoins de couvrir la majorité de ce que la plupart venait chercher sur code.spip (« comment utiliser telle ou telle fonction »)
- la vraie doc humaine, choisissant des exemples concrets et/ou des tutoriels est irremplaçable pour aller plus loin que le phpdoc automatique (que montrent IDE + Sourcegraph), mais ça c’est dans Programmer justement (et Contrib pour les plugins, et les Readme)
- en conséquence de quoi, code.spip ne semblant avoir quasiment plus aucune utilité pour ce qu’on venait y chercher (remplacé par IDE + Sourcegraph + les vraies docs), mon point de vue était qu’il serait plus clair de montrer « la recherche dans Tout Le Code » (et pas juste core et quelques plugins triés) sur le domaine code.spip en le remplaçant, plus utile et plus clair pour la plupart des gens
- et du coup pour les non-connoisseurs et les gens de passage, avoir moins de possibilité de s’y perdre, en n’ayant plus qu’une entrée dans le menu, ayant rapport au code automatisé (sourcegraph sur code.spip), et une entrée de vraie doc de chaque type (programmer.spip pour le core, et contrib.spip pour les plugins, lui-même fusionnant deux sites pour simplifier)