faut-il tuer doc.spip.org ?

Par James, jeudi 4 octobre 2007 à 21:21 :: SPIP a besoin de vous ::#427 ::rss

Le site de la documentation technique a pour objectif de réunir tout ce qui a trait au code de SPIP.

par code, on entend principalement le code php.

D’ailleurs, il est étroitement lié au dépôt de la version de développement, puisqu’il est alimenté par nos commits. Chaque répertoire est une rubrique, chaque fichier une sous-rubrique, et chaque fonction un article alimenté par les commentaires de l’application.

C’est la raison pour laquelle notre ami Piif fait un commit tous les soirs à 23h42, il met à jour le code quand il manque des commentaires, et le site est aussitôt mis à jour.

Bon en fait, c’est un robot qui bosse pour Piif :-)

Parallèlement à cela il est possible d’ajouter des informations, des astuces, des explications plus détaillés parce que le site marche avec le plugin crayons. Il faut être rédacteur, je crois.

Sinon, l’autre objectif est de fournir des articles qui détaillent des aspects très techniques de SPIP, et dans l’absolu, pas forcément autour du seul code en php. On aurait pu y placer des articles de spécifications techniques, par exemple, qui n’auraient pas forcément eu leur place sur la documentation officielle, plus orientée utilisateur (terme vague, je sais), et parlant avec précision de SQL, de Javascript, voire de CSS

Seulement voilà, personne ne s’en occupe, personne ne s’en sert et surtout, plus grave, personne ne le soutient :

Une doc sympa ? direction spip-contrib. Une idée ou une explication sur une fonction ? un wiki, un billet sur ce blog ou sur un autre.

La question, donc, c’est : à quoi bon ce site ? peut-on l’arrêter définitivement plutôt que de le regarder agoniser et fournir un flux rss inexploitable ?

Commentaires

1. jeudi 4 octobre 2007 à 22:50, par devine

faut-il tuer doc.spip.org ?

Je pense que doc.spip.org peut avoir comme utilité de compléter ce que Trac ne fournit pas. Par exemple, si j’ai besoin de savoir quand une fonction a disparu ou au contraire a été introduite ou encore a changé de signature, Trac est trop frustre, il faut lire toutes les versions de son fichier et comme souvent il est assez gros c’est très peu discriminant. En améliorant un peu le script de Pif, on devrait pouvoir donner tous les dépots qui ont affecté une fonction, ce qui est plus précis que tout son fichier, et en particulier ceux qui ont affecté son en-tête.

Si on arrive à faire ça, les flux RSS pourrait alors offrir un abonnement non sur article mais sur une collection de fonctions PHP de SPIP : j’ai écris une extension de SPIP qui repose sur telles fonctions que j’utilise ou surcharge, j’ai besoin d’être prévenu de leurs changements plutot que d’explorer l’historique de Trac quand la dernière version chargée se révèle incompatible avec mon code.

Qui s’y colle ? L’accusé (Pif) ou le juge (James) ?

2. jeudi 4 octobre 2007 à 23:08, par James

faut-il tuer doc.spip.org ?

Qui s’y colle ?

toi ?

3. jeudi 4 octobre 2007 à 23:53, par devine

faut-il tuer doc.spip.org ?

Ah non, moi je suis la partie civile

4. vendredi 5 octobre 2007 à 00:15, par devine

faut-il tuer doc.spip.org ?

Et puis je charge le cahier des charges : faire ausi un x-ref des fonctions appelées dans une fonction (je parle pas des globales, il n’y en a pas en SPIP, hein).

5. vendredi 5 octobre 2007 à 10:13, par Olivier G.

faut-il tuer doc.spip.org ?

D’un autre côté, j’imagine que documenter une fonction qui disparaît le lendemain pourrait être assez frustrant...

6. vendredi 5 octobre 2007 à 11:06, par Joseph

faut-il tuer doc.spip.org ?

Personne ne s’en sert et bien non. Personnellement je trouve ça super pratique. Quand on ne connait pas le code du core par coeur comme moi, et qu’apparaît une fonction dans le code que l’on ne comprend pas, un tour sur doc.spip me permet au moins, à défaut d’une description détaillée, de savoir dans quel fichier est déclaré cette fonction. A moi ensuite d’aller faire un tour dans le fichier source et d’essayer de comprendre le code.

Certes, ce serait un rêve que chaque fonction soit entièrement documentée sur doc.spip et nous en sommes loin. Je sais aussi qu’il s’agit d’un travail colossal. Mais, même imparfait, doc.spip a son utilité.

7. vendredi 5 octobre 2007 à 12:47, par James

faut-il tuer doc.spip.org ?

Joseph, personne ne dit que ce site est inutile, juste qu’il n’est pas vivant et que personne ne le soutient, nuance.

En gros, les vraies questions, c’est pourquoi personne n’ajoute de commentaire après avoir fait un petit examen du code ? Pourquoi on ne va pas « naturellement » sur ce site écrire de la doc technique ? Que faut-il faire pour que ce site joue pleinement son rôle ?

Compte tenu du peu d’observations faites au sujet de ce site sur les listes et sur le canal irc, j’estime être en droit de m’interroger sur son devenir, quitte à poser des questions un peu provocantes.

Et il n’y a pas d’accusations dirigées contre Piif, pis quoi encore ? :)

Quant à Olivier G., eh bien ... non rien :)

8. vendredi 5 octobre 2007 à 13:43, par ventrea

faut-il tuer doc.spip.org ?

Je vais régulièrement sur doc.spip.org pour une utilisation voisine de celle de Joseph, il me permet facilement de voir où est déclaré une fonction, quelles sont les inclusions .... et après de repartir sur la zone En gros c’est pour moi un explorateur de code avancé qui est accessible sur le web.

Pour la doc j’ai plus l’habitude de regarder les échanges des mailings list spip-dev et spip-zone.

Je ne pense pas qu’il puisse vivre autrement qu’en étant un générateur automatique (la petite phrase ajoutée dans le code qui décrit une fonction non triviale est parfois bienvenue) ; c’est déjà assez dur de suivre les commits si en plus il faut les comprendre et les documenter .... :-)

Pour les articles de fond sur la technique je pense qu’ils ont plus leur place sur le wiki de la zone ou spip.net

A+

9. vendredi 5 octobre 2007 à 18:08, par z’avez pas encore deviné ?

faut-il tuer doc.spip.org ?

Pour savoir dans quel fichier est une fonction, GREP suffit, pas besoin de sortir un navigateur. Alors je partage le sentiment de James : en l’état ce site n’a pas beaucoup d’utilité. Il n’en aura que s’il fournit un service plus synthétique que GREP ou le moteur de recherche de Trac. Mémoriser tous les dépots concernant une fonction serait un minimum, qui ne serait pas trop dur à faire. Mais Pif, il est où ton code ?

10. vendredi 5 octobre 2007 à 18:13, par Fil

faut-il tuer doc.spip.org ?

Je viens de débuguer l’histoire es liens et des rss qui donnaient des urls délirantes (merci les moteurs de recherche fous).

$profondeur_url = substr_count(reset(explode('?', $_SERVER['REQUEST_URI'])),'/') - 1; if ($profondeur_url AND !_DIR_RACINE) { include_spip('inc/headers'); redirige_par_entete('/'); }

11. vendredi 5 octobre 2007 à 18:19, par Mortimer

faut-il tuer doc.spip.org ?

Salut,

moi je l’utilise régulièrement quand je fais des plugins pour SPIP (ce qui est moins régulier ces jours ci, mais ce n’est pas une raison), ou quand qq pose une question sur irc. Je trouve tout ce que je veux en trois clicks alors que trac et totalement inutile pour trouver la fonction qu’on cherche, etc...

Par contre, le moteur de recherche est déjà mort, alors je passe par google : "verifier action site:doc.spip.org" et je trouve direct ce que je veux, pas de pbl.

Après, j’avais déjà mis des retours dans la doc, mais il y a plusieurs problèmes :

crayon n’a plus l’air de marcher sur le site, et c’est super lourd d’avoir à charger l’espace privé juste pour documenter une fonction, quand crayon etait là, ça allait tout seul
le squelette n’affiche pas les commentaires, ni les notes, ce qui fait que même si on voit qu’il y a eu commentaire sur une fonction ou un article, on peut rien faire avec
il y a bcp d’article de doc technique qui vaudrait le coup d’être porté du wiki spip-contrib sur doc.spip.org, juste pour garder une continuité dans les sites et que personne n’a le reflex d’aller voir le wiki de spip-contrib pour savoir comment écrire une nouvelle boucle, etc...

Alors, après, qui s’en oqp :

mon site (http://6v8.gamboni.org utilise un dérivé du squelette de la doc, avec les forums et autres infos qui marchent correctement, dès que j’ai une connexion internet à la maison (AOL sont des £"%$£%£"$!!!!), je pourrais commiter ses modifications si IZO n’y voit pas de pbl (mais là, il a autre chose à faire)
pour faire marcher gribouille et crayons sur doc.spip.org, je ne sais pas ce qu’il faut faire et il faut sûrement plus de droits que ceux que j’ai actuellement, donc je ne peux pas m’en oqp perso.
pour rapatrier les articles wiki de spip-contrib à doc.spip, je suppose qu’il faudrait y installer gribouille.

12. vendredi 5 octobre 2007 à 19:45, par James

faut-il tuer doc.spip.org ?

Mais Pif, il est où ton code ?

Tu demandes ? bah il est sur la zone, bien sur ! :)

13. vendredi 5 octobre 2007 à 21:49, par merci de respecter mon anonymat

faut-il tuer doc.spip.org ?

ok, vu. C’est donc assez déconnecté de chaque dépot, et ce à quoi je pense relève finalement peut-etre plus du développement de Trac lui-même, qui est lui aussi un projet ouvert (d’ailleurs ce serait bien d’avoir une version plus récente).

Ce qui me gêne peut-etre le plus dans doc.spip.org, c’est que c’est distant : il rajoute une ligne dans le code qui n’est pas informative en soi, seulement quand on clique dessus. Je préférerais la date d’apparition de cette fonction, et la liste des numéros de dépots qui l’ont changée : ça ne prendrait pas plus de place en moyenne, et personnellement ça m’aiderait plus.

14. dimanche 7 octobre 2007 à 17:28, par NicolasR

faut-il tuer doc.spip.org ?

Si j’ai bien compris :
1) le systeme "automatique" de doc.spip.org fonctionne bien et est utile pour s’y retrouver dans le code
2) c’est surtout utilisé par ceux qui travaillent sur les plugins (les devs core s’en servent-ils ?)
3) le squelette de doc demande des mises au point et n’est pas vraiment suivi
4) l’activité éditoriale de doc est au point mort, voire n’a jamais vraiment démarrée

Manifestement il y a un problème de limites de ressources humaines disponibles, je ne vois pas ce qui peut améliorer ce point, et tout ce qui peut être analysé et imaginé ne doit pas l’oublier : "qui peut faire et quand ?"

il y a bcp d’article de doc technique qui vaudrait le coup d’être porté du wiki spip-contrib sur doc.spip.org, juste pour garder une continuité dans les sites et que personne n’a le reflex d’aller voir le wiki de spip-contrib pour savoir comment écrire une nouvelle boucle, etc...

On pourrait tout aussi bien retourner la proposition et dire qu’il aussi logique que des informations utiles pour faire des plugins ont leur raison d’être sur SPIP-Contrib. Ce qui justifie probablement, outre les raisons historiques, le fait que justement ces articles y aient été écrit. Ce qui est clair est qu’il manque des repères de choix.

Quand à déshabiller Pierre (contrib) pour habiller Paul (doc), outre l’important travail et les incohérences que cela entrainerait sur l’existant (ces articles sont parfois bourrés de liens interne à Contrib, de liens externes pointants dessus, et de fichiers divers), cela ne créerait probablement pas pour autant de dynamique éditoriale sur doc, ni ne résoudrait la difficulté de savoir ou est quoi (sur contrib, sur doc ?).

Je pense que l’erreur est de concevoir nos sites de doc techniques comme des univers indépendant qui devraient chacun d’entre eux disposer de tout le panel. Au contraire il me semble que vu nos forces limitées nous devons mutualiser au maximum les choses, en s’obligeant à : 1 thême = 1 et 1 seul endroit + une navigation intersite systématique

Donc le constat est que :
doc dispose d’un systeme "automatique" de "glossaire de la doc" qui marche
contrib dispose d’un wiki et d’articles qui vivent avec une base de textes existants (pas toujours à jours mais bon)
une page commencée en wiki sur contrib, basculée ensuite en article quand c’est justifié voit son audience multipliée par plus de 20 et dispose alors d’un forum et autres outils.
l’objectif de contrib est de devenir une sorte de "source forge" de la doc des contribs, imbriquée avec la Zone ("source forge" du code) et les moyens de distribution, ce qui est partiellement déjà fait
des deux cotés les forces sont très limitées, donc autant ne pas se disperser ni refaire ce qui fonctionne.

Proposition

Je propose de mieux intégrer le tout, sous une forme technique à définir :
soit doc devient physiquement un secteur de contrib (avec ses propres squelettes éventuellement), en admettant que le code des automatismes le permette
soit les deux sites sont mutualisés (inclus éventuellement sur un même SPIP) sur la même plateforme d’hébergement ce qui permet de tisser massivement des liens fiables entre les deux (les deux sites étant perçus comme des parties d’un même ensemble) et de regrouper les efforts des équipes techniques.
dans cette optique le wiki et les articles de contrib sur la doc technique deviennent communs, ce qui supprime la question de "ou est quoi"
soit au contraire on se dit que : "doc.spip.org documente le core alors il doit être mutualisé avec spip.net et devenir une sorte de glossaire automatique du core, et rien que ça", la partie wiki, articles, etc .. non "officielle" etc ... étant traitée sur Contrib.
soit comme dit les automatismes de doc sont intégrés à Trac qui est le lieus de production du code, et doc disparait en tant que tel, Contrib reprend le reste
soit .. euh !!!

@+ NicolasR

15. dimanche 7 octobre 2007 à 17:33, par NicolasR

faut-il tuer doc.spip.org ?

Ce n’est vraiment pas pratique que le "quote" n’ai pas de style qui le distingue vraiment sur le blog, cela ne permet pas de quoter correctement

16. dimanche 7 octobre 2007 à 21:53, par encore moi

faut-il tuer doc.spip.org ?

Tout à fait d’accord avec Nicolas : en multipliant les sites on minimise les possibilités d’interventions, les infos de doc.spip.org seraient plus visibles sur Contrib ou Spipnet. Une fusion avec l’un d’eux me semble souhaitable (attention à la sécurité cependant).

Du point de vue de l’utilité, Contrib me semble plus indiqué : c’est bourré d’articles parlant des fonctions que doc.spip.org documente, pouvoir utiliser les raccourcis internes pour les référencer devrait inciter à faire vivre ces infos.

A l’inverse, Spipnet est fait pour documenter l’utilisation de SPIP, pas son implémentation, je ne crois pas judicieux de mélanger ces deux types d’information.

17. lundi 8 octobre 2007 à 14:13, par James

faut-il tuer doc.spip.org ?

Ce n’est vraiment pas pratique que le "quote" n’ai pas de style qui le distingue vraiment sur le blog, cela ne permet pas de quoter correctement

Tu as raison, j’essaie d’arranger ça ce soir ;

18. lundi 8 octobre 2007 à 15:46, par Mortimer

faut-il tuer doc.spip.org ?

Il y a aussi une question d’audience...

Les gens qui vont voir spip-contrib sont souvent des débutants, ou des gens qui n’ont pas l’envie/les capacités d’écrire des plugins.

Ceux ci n’ont donc pas d’interet à lire doc.spip.org. ça risque même d’ajouter du bruits qui leur fera peur...

Il est vraie que centraliser, relier les choses seraient bien, mais il faut faire attention à ne pas effrayer les utilisateurs.

19. mercredi 10 octobre 2007 à 03:02, par un utilisateur nostalgique !

faut-il tuer doc.spip.org ?

Nous le utilisateurs lambda quand o a adopté Spip c’est parce qu’on ne voyait pas tout ce tralala de codeurs ! c’était une belle voiture pratique et esthétique voire modulable à souhait ! Aujourd’hui Spip ressemble a une voiture desossé au garage chaque jour sans qu’on sache pourquoi ! tout le mnde regarde ce qu’il y a sous le capot ! mais on a oublié que Spip oit roule sans que tout le monde voit forcèment le moteur ou sous e capot ! je dis ça parce que je suivais bien l’évolution de Spip avant ; maintenat c’est inaccessible pour moi je ne sis même pas où trouver les bonnes versions, c’est quoi ces plugin inachevé qui marche, puis pas du tout puis aucune cohérence ! ca ressemble à Microsoft maintenant ! couche sur couche en attendat des jours meilleus et pourquoi ces mises à jours quotidiennes ? il faut peut être laisser le temps à la reflexion et une stratégie de dévelopement et d’évolutio ! on dirait une parade de programmeurs qui roulent les mecaniques ! Avant, par exemple, une mise à jour était vite adapté et adopté par l’untilisateur ; auord’hui je n’ai profité de très très peu de mise à jour et car trop complexes inachevé ou ne marche plus par la suite ou incompatible ! à titre d’exemple, le plugin Agenda il n y a pas un utilisateur novice voir qui n’est pas informaticien qui a su l’implanter, le couteau suisse marche pas chez moi avec SVN , google map qui l’utilise ? les formulaires test quiz j’ai beau esayé rien ! pourtant aant toute nouveauté marchait à merveille ! Il va falloir vraiment revenir au sources les gars vos enchères et zèles de programmation ne nous mènent nulle part ! Avec bcp de regrets ! vivement une maturité et la simplicité d’avant !

20. mercredi 10 octobre 2007 à 08:28, par Committo, Ergo Sum

faut-il tuer doc.spip.org ?

Je trouve gros de se plaindre de la difficulté de suivre les évolutions de SPIP aujourd’hui, lorsqu’on se permet de mettre sur un fil de discussion des réflexions qui n’ont rien à voir avec lui. Est-ce un comportement "mature" et "simple" ? En allant au bon endroit, savoir la liste de discussion spip-dev, on trouve les réponses à ces questions et beaucoup moins de contre-vérités.

21. mercredi 10 octobre 2007 à 10:11, par cam.lafit

faut-il tuer doc.spip.org ?

Bonjour

Bon je découvre un peu sur le tard cet article. Je dois dire que je ne suis pas trop l’actualité du blog. ^^

Non ne tuez pas doc.spip.org, mine de rien il est utile. Si si c’est vrai.

Bon il a des défauts, ok. Mais bon on n’es pas à un détail prés.

Les propositions de NicolasR semblent pas mal. (wiki, ...)

Pour ma part, je trouve plus pertinent d’avoir :
la doc technique : doc.spip
la doc pratique : contrib
la doc utilisateur : spip.net

Par exemple, je n’ai pas le reflexe de me loguer ici, alors que si les articles etaient en wiki et cette fonction clairement indiquée, ça serait pratique. On fait une recherche, on trouve, on édite.

Apres le pb récurrent, elle est où la ressource humaine ?

Sauvons doc.spip.org

faut-il tuer doc.spip.org ?

Commentaires

Ajouter un commentaire

Calendrier

Archives

Catégories

Langues

SPIP Gazette #2

Les prochains RDV SPIP

Liens

Syndication

« octobre 2007 »
lun.	mar.	mer.	jeu.	ven.	sam.	dim.
1	2	3	4	5	6	7
8	9	10	11	12	13	14
15	16	17	18	19	20	21
22	23	24	25	26	27	28
29	30	31