Gestion des versions de documentations, avant tout

Avec l'arrivée imminente de code.spip.net, et en ayant en tête les prochains sites spécifiques possibles pour vider spip.net (rediger.spip, integrer.spip), je pense qu'il faut s'interroger de toute urgence sur la manière dont on doit gérer les changements de version lorsqu'il y a des évolutions majeures.

Cela n'a pas été vraiment prévu pour programmer.spip.net, et c'est normal vu l'énorme boulot qu'avait déjà abattu Marcimat.

Mais justement ! : au regard de cette expérience, et du fait que "programmer3" est toujours dans un état bâtard, et n'est toujours pas sur l'URL "première" alors qu'il s'agit pourtant de la version stable, et bien il faut décider d'une méthode, en *amont* de tout site de documentation.

Sinon dans un ou deux ans, on va se retrouver dans les mêmes situations, à avoir des sites difficile à bouger et à mettre à jour, voir complètement bloqués.

Je crois que ce serait pas mal d'arriver à déterminer une *même méthode* qui serait appliquée à l'ensemble des sites de doc.

Doit-on vraiment créer un nouveau site différent à chaque fois que des changements majeurs se font (X qui change, ou Y qui change avec beaucoup d'ajouts) ? Avec une URL différente en plus ? Doit-on plutôt faire un site unique, avec des liens entre les versions d'une même fonction lors qu'une même doc existe dans plusieurs version ?

Prenez la documentation (très bien faite, je trouve) de Symfony :
http://symfony.com/fr/doc/current/book/routing.html
pour tel point précis, on a la document "current" (qui est un alias de la version stable en cours "2.2") + des liens vers les versions précédentes ainsi que même la version en dev.

Parfois les documentations n'ont pas bougé et sont exactement les mêmes : peu importe. Il y a un processus de copie à chaque fois, et les versions précédentes à mon avis ne bougent plus.
Mais ce n'est pas séparé, il y a un lien entre les versions.

Voilà, qu'en pensez-vous ? Êtes-vous d'accord, autant que faire se peut, d'essayer de trouver une méthode qui convienne à toutes les docs ?

Cela permettrait de ne pas se poser de questions sur l'implémentation dès que l'on se décidera à lancer un écrémage de spip.net vers des mini-sites plus spécialisés.

(Cela vient notamment d'une réflexion récente qu'en fait, ça sera vraiment trop compliqué de modifier spip.net tant qu'on ne l'aura pas réellement vidé pour ne garder que l'aspect "portail".)

Pour être plus "todolist", je pense qu'il faut, à peu près dans l'ordre :

1) trouver une méthode pour gérer les versions, ou deux maximum si vraiment un site demande une manière de gérer différente
2) appliquer cette méthode à programmer.spip
3) sortir officiellement code.spip en ayant déjà intégré dès le démarrage cette histoire de version
4) sortir l'intégration squelettes dans un site à part, avec le système de version, et en gérant les redirections (cf référencement et liens pointant sur spip.net)
5) même opération pour la doc de rédaction et d'administration (d'ailleurs "editer.spip" serait peut-être mieux comme nom pour ne pas parler que de rédaction)
6) enfin refondre le portail, ne contenant plus que la description générale, la liste des versions, et plein de jolies pages redirigeant aux bons endroits suivant les profils (user, dev, graphiste, etc)

Go ? Une groupe de travail pour réfléchir *spécifiquement* au problème du versionning de documentation ?

--
Vincent

Hello,

Le 09/03/2013 09:30, Vincent Finkelstein a écrit :

Avec l'arrivée imminente de code.spip.net,

Ah ?

[...]

Mais justement ! : au regard de cette expérience, et du fait que "programmer3" est toujours dans un état bâtard, et n'est toujours pas sur l'URL "première" alors qu'il s'agit pourtant de la version stable, et bien il faut décider d'une méthode, en *amont* de tout site de documentation.

Dans un état bâtard ? bah, en attendant, il est là, et personne ne s'en est occupé à ce que je sache, ni moi ni un autre.

Sinon dans un ou deux ans, on va se retrouver dans les mêmes situations, à avoir des sites difficile à bouger et à mettre à jour, voir complètement bloqués.

Je ne vois pas en quoi programmer3 est bloqué ? faut juste que quelqu'un prenne le temps de s'en occuper… on peut juste pas chasser 2 lièvres à la fois.
Pour info, je me rappelle m'avoir dit (^^) qu'il serait bien depuis programmer de pouvoir lier des infos vers une documentation des fonctions, afin de ne pas avoir à le gérer dans programmer (genre sql_truc(), le décrire mais pas en détail, le détail, serait ailleurs).

Du coup, j'ai avancé sur cet espace de documentation du code. Il est dans un certain état ( http://autodoc.magraine.net/spip-dev/zora/ ) qui ne semble pas convenir à tout le monde. J'ai aussi une autre url en préparation qui intègre ça, avec un SPIP contenant les archives de doc.spip.org destiné à code.spip.net effectivement. C'est un stand by là. D'autant que tu sembles dire que ça va pas aller si ça ne gère pas les différentes versions de SPIP. Je rappelerais par ailleurs que les versions < 3 n'ont aucun phpdoc exploitable, et sur la 3.0 c'est pas la panacée non plus.

Je crois que ce serait pas mal d'arriver à déterminer une *même méthode* qui serait appliquée à l'ensemble des sites de doc.

Doit-on vraiment créer un nouveau site différent à chaque fois que des changements majeurs se font (X qui change, ou Y qui change avec beaucoup d'ajouts) ? Avec une URL différente en plus ? Doit-on plutôt faire un site unique, avec des liens entre les versions d'une même fonction lors qu'une même doc existe dans plusieurs version ?

Prenez la documentation (très bien faite, je trouve) de Symfony :
http://symfony.com/fr/doc/current/book/routing.html

Dans le cas de symphony (quelle ironie je trouve cette page avec l'url fr/ et le reste de l'url en anglais…), leur doc est gérée via des fichiers https://github.com/symfony-fr/symfony-docs-fr , au format rst (http://fr.wikipedia.org/wiki/ReStructuredText) donc, qui sont dans le répertoire docs/ , à la racine de chacun de leur projet, et écrite par les développeurs au moment où ils codent, mise à jour par ces mêmes développeurs. Pour «Le Book» c'est un truc à part, mais aussi via github et le format rst.

Les liens peuvent se faire entre traductions parce qu'ils ont la même arborescence et les mêmes URL au nom de la langue près.

pour tel point précis, on a la document "current" (qui est un alias de la version stable en cours "2.2") + des liens vers les versions précédentes ainsi que même la version en dev.

Parfois les documentations n'ont pas bougé et sont exactement les mêmes : peu importe. Il y a un processus de copie à chaque fois, et les versions précédentes à mon avis ne bougent plus.

C'est une nouvelle branche via git, on les retrouve là https://github.com/symfony/symfony-docs

Mais ce n'est pas séparé, il y a un lien entre les versions.

Même url… avec une gestion des changements par https://github.com/symfony/symfony-docs/blob/master/redirection_map

Voilà, qu'en pensez-vous ? Êtes-vous d'accord, autant que faire se peut, d'essayer de trouver une méthode qui convienne à toutes les docs ?

Mais être d'accord sur quoi ?

Si je récapitule donc, il faudrait pour chaque site
- pouvoir passer d'une branche à une autre
- pouvoir passer d'une traduction à une autre

Le tout sur le même site ?

J'étais parti, pour programmer, du principe qu'on duplique la bdd au moment de la nouvelle version (comme symfony qui fait une branche github).
Si ce principe est à revoir, pourquoi pas, parlons-en. On peut aussi décider de tout basculer sur github aussi hein, mais on risque de perdre encore d'autres rédacteurs !

Cela permettrait de ne pas se poser de questions sur l'implémentation dès que l'on se décidera à lancer un écrémage de spip.net vers des mini-sites plus spécialisés.

(Cela vient notamment d'une réflexion récente qu'en fait, ça sera vraiment trop compliqué de modifier spip.net tant qu'on ne l'aura pas réellement vidé pour ne garder que l'aspect "portail".)

Il faut surtout du temps (beaucoup de chez beaucoup), des gens et des volontés. C'est impossible tout seul !

Pour être plus "todolist", je pense qu'il faut, à peu près dans l'ordre :

1) trouver une méthode pour gérer les versions, ou deux maximum si vraiment un site demande une manière de gérer différente

Que proposes tu ? n'oublies pas aussi la gestion des traductions !

2) appliquer cette méthode à programmer.spip

Je peux te donner les clés de mon serveur si tu veux :slight_smile:

3) sortir officiellement code.spip en ayant déjà intégré dès le démarrage cette histoire de version
4) sortir l'intégration squelettes dans un site à part, avec le système de version, et en gérant les redirections (cf référencement et liens pointant sur spip.net)
5) même opération pour la doc de rédaction et d'administration (d'ailleurs "editer.spip" serait peut-être mieux comme nom pour ne pas parler que de rédaction)
6) enfin refondre le portail, ne contenant plus que la description générale, la liste des versions, et plein de jolies pages redirigeant aux bons endroits suivant les profils (user, dev, graphiste, etc)

Go ? Une groupe de travail pour réfléchir *spécifiquement* au problème du versionning de documentation ?

Par ailleurs : le mieux est l'ennemi du bien.

MM.

Le 10/03/2013 14:06, Matthieu Marcillaud a écrit :

Avec l'arrivée imminente de code.spip.net,

Ah ?

Mais si, mais si, ça ne va pas tarder, je le sens ! :slight_smile:

Dans un état bâtard ? bah, en attendant, il est là, et personne ne s'en
est occupé à ce que je sache, ni moi ni un autre.

L'état bâtard c'est de n'être pas vraiment officialisé, avec un domaine que j'estime temporaire (avec le 3 dedans), faute d'avoir terminé de définir une procédure exacte quand on change de version.

Quand on arrive depuis la boussole, on tombe toujours sur l'ancien ! (ce qui est normal, l'URL "officielle" devant rester la même évidemment, mais ne pas pointer sur la même chose...)

Je ne vois pas en quoi programmer3 est bloqué ? faut juste que quelqu'un
prenne le temps de s'en occuper… on peut juste pas chasser 2 lièvres à
la fois.
Pour info, je me rappelle m'avoir dit (^^) qu'il serait bien depuis
programmer de pouvoir lier des infos vers une documentation des
fonctions, afin de ne pas avoir à le gérer dans programmer (genre
sql_truc(), le décrire mais pas en détail, le détail, serait ailleurs).

Oui, je suis plutôt d'accord avec cette approche pour ne pas faire des doublons de doc (mais à voir comment ça peut s'intégrer quand on génère une version papier).

Du coup, j'ai avancé sur cet espace de documentation du code. Il est
dans un certain état ( http://autodoc.magraine.net/spip-dev/zora/ ) qui
ne semble pas convenir à tout le monde. J'ai aussi une autre url en
préparation qui intègre ça, avec un SPIP contenant les archives de
doc.spip.org destiné à code.spip.net effectivement. C'est un stand by
là. D'autant que tu sembles dire que ça va pas aller si ça ne gère pas
les différentes versions de SPIP. Je rappelerais par ailleurs que les
versions < 3 n'ont aucun phpdoc exploitable, et sur la 3.0 c'est pas la
panacée non plus.

Oui, je pense que la doc technique, même auto ou semi-auto, doit aussi savoir gérer les passages de flambeau régulièrement, tout comme les sites entièrement manuels.

Après ce ne sera pas forcément avec la même méthode (duplication de base ou pas, etc), c'est à voir comment ce sera le mieux (et c'est pour ça que je dis une ou deux méthodes maximum à définir pour l'ensemble des sites).

Pour ce qui est des anciennes versions, ben... on s'en fout, on ne crée pas des documentations "post-mortem"... Les nouvelles documentations démarrent à partir de l'actuel, c'est déjà assez de boulot comme ça. C'est pour les passages aux versions qui viendront que je pose ces questions.

Par ailleurs, à propos de cet espace Code + API, il faut noter que c'est *le* site de doc, parmi les autres qui sera différent, et donc les passages de version ne se feront pas forcément pareil. Il est un peu "à part" dans la réflexion quoi.

Mais être d'accord sur quoi ?

Si je récapitule donc, il faudrait pour chaque site
- pouvoir passer d'une branche à une autre
- pouvoir passer d'une traduction à une autre

Le tout sur le même site ?

Absolument pas (obligé) !

Je me reprends si ce n'était pas clair : ça c'est à définir justement, c'est ce que je demande : non pas copier telle méthode de telle autre communauté, mais réfléchir une bonne fois pour toute à ce qui sera le mieux pour nos sites à nous.

Mais y réfléchir et le décider en amont. C'est pas une question d'avoir "le mieux" (qui serait l'ennemi du bien), c'est une question de penser, pour une fois, à concevoir les choses en amont et en commun, plutôt que toujours s'en occuper à l'arrache à la fin, et tout seul. Et sans le faire jusqu'au bout. Et sans le noter nulle part. Sans formaliser les choses. C'est justement, à mon avis, un des points qui fait que c'est seulement une personne qui s'en occupe.

J'étais parti, pour programmer, du principe qu'on duplique la bdd au
moment de la nouvelle version (comme symfony qui fait une branche github).
Si ce principe est à revoir, pourquoi pas, parlons-en. On peut aussi
décider de tout basculer sur github aussi hein, mais on risque de perdre
encore d'autres rédacteurs !

Et donc, conséquence des paragraphes précédents : ça se trouve ce qui a été commencé pour programmer est tout à fait la bonne méthode, je ne sais pas. Mais justement il faut en discuter, de ce point précis, et le *compléter* pour avoir une procédure complète sous la main, lors d'un changement de version.

Il faut surtout du temps (beaucoup de chez beaucoup), des gens et des
volontés. C'est impossible tout seul !

Il faut du temps et des gens pour concevoir des choses et les poser clairement sur le papier (enfin sur un endroit fixe). Une méthode.

Une fois que cette étape est faite, bien sûr qu'il faudra toujours des gens, mais ce sera quand même plus facilement interchangeable, et d'autres pourront plus facilement contribuer, y compris pour monter d'autres sites similaires en ayant moins peur (car en ayant déjà des méthodes de travail sous la main).

Je ne parle pas du fait de *s'occuper* de la doc, au sens de la remplir, gérer l'éditorial, etc. Ça on est d'accord qu'il faut vraiment beaucoup de temps et de gens. Mais c'est une autre étape.
Là, pour l'instant, je parle modestement de ce qu'il y a en amont : càd la mise en place, la gestion et la mise à jour le moment venu, de *l'outil* qui sert à faire la doc.

Et d'ailleurs ce point qui me préoccupe rejoint ta phrase : c'est justement parce qu'il faut déjà beaucoup de temps pour s'occuper réellement de la doc, que ce serait bien d'avoir des méthodes définies en avance pour gérer les sites et leurs mises à jours, pour ne pas passer trop de temps sur ces points. D'autant plus pour les prochains sites qu'il pourra y avoir sur le même modèle.

Avoir chaque site complètement indépendant, tous gérés de manière différente, etc, ce n'est vraiment pas le bon plan à mon avis : ça bouffe trop d'énergie.

1) trouver une méthode pour gérer les versions, ou deux maximum si
vraiment un site demande une manière de gérer différente

Que proposes tu ? n'oublies pas aussi la gestion des traductions !

Peut-être bien que la duplication de base est la bonne solution, à discuter et à voir si ça couvre bien tous les cas.

Et justement à propos de traduction... Avec cette méthode de dupliquer la base, pour l'instant on disait que le principe c'était de bloquer alors l'écriture sur les anciennes versions.

Pour la langue de référence ok, mais quid des traductions ? Peut-on vouloir continuer à traduire les anciennes docs, même si elles n'augmentent plus ? À décider aussi.

En tout cas, si on choisit la méthode "duplication de base", il ne faut pas en rester à ce constat ! Il faut aussi définir :

- où duplique-t-on quoi ?
- l'URL "de référence" pointe toujours sur la version stable en cours ?
- les archives, qui sont donc des bases et sites séparés, sont alors en d'autres sous-domaine ou en sous-dossier ? (remarque : il est plus facile d'utiliser le caractère "." pour un nom de sous-dossier que pour un nom de sous-domaine où il a une autre signification, or les versions de doc ne seront pas forcément qu'à chaque version majeure...)
- si le rangement est bien toujours le même, peut-être y a-t-il moyen de faire des liens croisés, lorsque les mêmes pages existent ?
- bloque-t-on entièrement l'écriture pour les anciennes versions ? y compris la trad ?

Tout ça il faut en faire une "feuille de route".
Dans la rubrique "chantier de documentation" du wiki, on peut peut-être ouvrir une page sur ce point-là ?

2) appliquer cette méthode à programmer.spip

Je peux te donner les clés de mon serveur si tu veux :slight_smile:

Tu sais, c'est pas pour faire chier le monde hein. Ce que je veux avant tout c'est justement qu'on définisse quelques méthodes à *partager*, qu'on soit tous ok dessus, pour que ce ne soit pas UNE personne qui sache comment faire ceci-cela pour gérer un site de doc.

Par ailleurs : le mieux est l'ennemi du bien.

Cf ma précédente remarque là-dessus.

--
Vincent

--
RastaPopoulos

zut, pas passé sur la liste

Le 11 mars 2013 à 09:49, Maïeul Rouquette <maieul@maieul.net> a écrit :

Je suis un partisan de "on duplique la base". Voici les remarques suite à tes questions

Pour la langue de référence ok, mais quid des traductions ? Peut-on vouloir continuer à traduire les anciennes docs, même si elles n'augmentent plus ? À décider aussi.

En tout cas, si on choisit la méthode "duplication de base", il ne faut pas en rester à ce constat ! Il faut aussi définir :

- où duplique-t-on quoi ?

- le contenu de chaque site vers une archive suffixé du numero. Par exemple "integrer.spip.net" devient "integrer21.spip.net" lors du passage à la 3.

- l'URL "de référence" pointe toujours sur la version stable en cours ?

oui, œuf course. On pourrait imaginer un bandeau en haut pour indique le numero de version

- les archives, qui sont donc des bases et sites séparés, sont alors en d'autres sous-domaine ou en sous-dossier ? (remarque : il est plus facile d'utiliser le caractère "." pour un nom de sous-dossier que pour un nom de sous-domaine où il a une autre signification, or les versions de doc ne seront pas forcément qu'à chaque version majeure…)

plutot sous-domaine, mais j'ai pas d'objection à sous dossier

- si le rangement est bien toujours le même, peut-être y a-t-il moyen de faire des liens croisés, lorsque les mêmes pages existent ?

oui

- bloque-t-on entièrement l'écriture pour les anciennes versions ? y compris la trad ?

je serais d'avis de bloquer tt écriture pour le fr, mais pas pour la trad

++
Maïeul

Je sais plus où on en est mais :

- Moi je serais d'avis de ne proposer de traduire (et documenter) que la dernière version. C'est déjà assez compliqué / long comme ça, si en plus les documentateurs et traducteurs doivent reporter leurs choses sur les anciennes versions.

- Comme le fait remarquer Rasta, le sous-domaine ça peut être pas très joli effectivement.

On peut imaginer aussi
- programmer.spip.net qui redirige sur programmer.spip.net/3.0/
- programmer.spip.net/2.1/ archive figée
- programmer.spip.net/dev/ future...

Je veux bien regarder ce côté de migration, si on continue de garder 1 site SPIP par sous rubrique.
Si tout est regroupé dans un site c'est déjà plus compliqué à faire migrer.

Si on considère que des anciennes versions sont totalement figées, on peut imaginer un outil d'export qui rend statique le site figé (hors recherche évidemment). J'imaginais un répertoire lespip/static/ avec les fichiers HTML du site et un .htaccess qui regarde s'il existe l'url demandée en tant que fichier html, si oui, l'ulitise, si non appelle SPIP qui le créera. Le problème (si c'en est un) c'est que les stats ne seraient plus calculées pour ces pages statiques ensuite. Mais ça éviterait de faire charger SPIP pour un site qui n'a plus de vie, hors lecture du cache.

MM.

Le 10/03/2013 21:41, RastaPopoulos a écrit :

Le 10/03/2013 14:06, Matthieu Marcillaud a écrit :

Avec l'arrivée imminente de code.spip.net,

À ce propos, si des gens veulent réagir…

Ce que j'imaginais était

http://code.spip.net/ qui serait un site expliquant des concepts et API de SPIP avec des interactions possibles (en plus de la rédaction d'articles), du genre commentaires constructifs tel que sur php.net : « Vous pouvez proposer un exemple d'utilisation ». Mais il n'a pas vocation à servir de lieu de débug ou d'entraide !

En plus de ça, il y a un espace pour la doc automatique issue du code.

Ça donnerait (tel que c'est actuellement migré dans mon espace de test : http://postimage.org/image/3tzz3l1xv/) :

code.spip.net/archives pour les archives de doc.spip.net que j'ai récupérées
code.spip.net/autodoc/ avec le contenu de http://autodoc.magraine.net/spip-dev/zora/ avec la possibilité de proposer des améliorations aux phpdocs

- code.spip.net est un SPIP
- /autodoc/ est un site statique HTML issue de phpdocumentor

Les URLs code.spip.net/autodoc/@x redirigent sur la fonction comme le fait doc.spip.net/@x

Questions en vrac :

A) que manquerait t'il pour sa mise en ligne ?
B) gère t'on les traductions sur le SPIP ? si oui, comment ?
C) gère t'on les versions de SPIP ? si oui, comment ?
D) sur l'autodoc (qui n'a pas de traduction), gère t'on différentes versions de SPIP, si oui, comment ?

Voilou :slight_smile:

Salut Matthieu, et tou-te-s. C’est génial que tu aies pu trouver le temps et l’énergie pour faire tout ce boulot que tu nous présentes ! Le site est déjà tellement avancé qu’il pourrait avantageusement remplacer doc.spip.org. Il y aurait donc deux parties, un SPIP « rédigé » manuellement et qui concernerait seulement les APIs, et un « autodoc» extrait automatiquement des fichiers source et qui concernerait toutes les fonctions définies dans le code source ? C’est cool, la partie autodoc serait donc continuellement à jour sans trop d’efforts ! J’imagine que les exemples seraient proposés seulement sur la partie « rédigée », sous forme de commentaires ou d’articles liés à une API ? En tous cas c’est une excellente idée de permettre de proposer des exemples ! Pour éviter trop de travail de relecture j’imaginais que les exemples pourraient être publiés directement, sans avoir été contrôlés ni validés par un admin, puis seulement ensuite, « appréciés » (notés) par les visiteurs eux-mêmes. Il pourrait y avoir un statut « testé et validé » (éventuellement «… par X utilisateurs »). Un admin pourrait passer sur le site, mais seulement de temps en temps, pour éliminer les exemples douteux… L’appel aux commentaires constructifs pourrait en outre préciser « Vous pouvez proposer un exemple d’utilisation ». Il faudra simplement rappeler l’existence de , des listes de discussion et du canal IRC pour éviter que les visiteurs posent des questions plutôt que proposent des exemples. C’est un peu ce qui, dans la doc php, s’appelle les « user contributed notes », ou alors dans stack overflow, le bloc « votes / answers ». Moins de boulot pour les admins, plus grand nombre de validateurs possibles ! Pour les trads, vu l’impact de SPIP en dehors de la communauté francophone, est-ce que ça vaut vraiment la peine ? Juste prévoir que les articles (de la partie rédigée) puissent être traduits. Pour les versions de SPIP sur autodoc, c’est la version en cours qui devrait être affichée par défaut (comme actuellement sur zora). Si c’est pas trop dur d’indiquer à phpDocumentor quel répertorie il doit parser, on peut imaginer une variable dans l’url : ?branche=3.0 ou ?branche=dev. A noter : l’exemple de php qui propose une documentation non pas par version mais par fonction, en indiquant une « zone de compatibilité ». Par exemple ici on a la doc de money_format et on sait qu’elle est valide pour php4 > php4.3 + php5 En conclusion, je serais d’accord pour publier tout de suite l’excellent travail qu’a fait Matthieu, quitte à le faire évoluer par la suite. Publier ce travail n’impacte en rien les développements futurs (comme par exemple si on veut rédiger un article par élément de doc ou créer un objet éditorial nouveau par élément de doc). Merci Matthieu ! A+ Cyril

Face à ce bel écho, je livre mes réponses :slight_smile:

Le 18/03/2013 12:55, Matthieu Marcillaud a écrit :

Questions en vrac :

A) que manquerait t'il pour sa mise en ligne ?

Ce que je pense, c'est que, c'est déjà mieux qu'avant, et que donc, bah, ce qui est fait et fait qu'on peut le mettre en ligne ?

B) gère t'on les traductions sur le SPIP ? si oui, comment ?

Je pense qu'il faut effectivement gérer les traductions.
Un secteur par langue me semble pas mal, avec des liens de traductions entre les éléments.

Ça donnerait c.s.n/en/... c.s.n/fr/...

Ainsi les API pourraient être traduites, si des motivés sont là.

C) gère t'on les versions de SPIP ? si oui, comment ?

Je dirais oui, mais à la PHP, c'est à dire indiquer la plage de version de l'api sur chaque élément. Ne pas faire un article pour la version 3 et un pour la version 3.1 par exemple.

Ça donnerait c.s.n/fr/apis/cvt/charger par exemple
ou c.s.n/fr/apis/sql/sql_select

Si c'est traduit, ça sous-entend qu'on ne peut se suffire d'extraire automatiquement les données de l'autodoc pour une API, puisque celles si ne sont pas traduisible, et que donc, l'objet qui accueille la fonction (un article ou un objet spécifique) doit pouvoir recevoir soit un texte décrivant chaque élément de la fonction (arguments, types, retours...) soit avoir des liaisons ou des champs spécifiques à remplir. Le cas des liaisons est … difficile à gérer car il peut y en avoir beaucoup, et à traduire ça serait tout aussi casse pied. Je me demande si un format texte (ou pourquoi pas la même écriture que le phpdoc) ne serait pas aussi bien. Ainsi on enregistrerait le phpdoc de la fonction dans un champ de l'objet et il pourrait être traduit, puis analysé à l'affichage donc.

D) sur l'autodoc (qui n'a pas de traduction), gère t'on différentes versions de SPIP, si oui, comment ?

Je pense que l'autodoc est quelque chose exclusivement pour les développeurs et que… partant de ce point de vue, il serait inutile de faire afficher différentes versions, mais uniquement la dernière version en développement.

Cela dit, techniquement ce n'est pas compliqué d'avoir autodoc/dev/ et autodoc/3.0/ ...

Techniquement non plus ça ne serait pas compliqué d'avoir
- autodoc/dev/ qui aurait toutes les fonctions du monde entier
- et autodoc/3.0/ qui ne listerait que ce qui est déclaré avec @api (resterait plus grand chose, et plein de @see seraient sans suite)

À voir…
Y a des remarques ?

MM.

Le 19 mars 2013 13:07, Matthieu Marcillaud <marcimat@rezo.net> a écrit :

Face à ce bel écho, je livre mes réponses :slight_smile:

Le 18/03/2013 12:55, Matthieu Marcillaud a écrit :

Questions en vrac :

A) que manquerait t'il pour sa mise en ligne ?

Ce que je pense, c'est que, c'est déjà mieux qu'avant, et que donc, bah,
ce qui est fait et fait qu'on peut le mettre en ligne ?

B) gère t'on les traductions sur le SPIP ? si oui, comment ?

Je pense qu'il faut effectivement gérer les traductions.
Un secteur par langue me semble pas mal, avec des liens de traductions
entre les éléments.

Ça donnerait c.s.n/en/... c.s.n/fr/...

Ainsi les API pourraient être traduites, si des motivés sont là.

C) gère t'on les versions de SPIP ? si oui, comment ?

Je dirais oui, mais à la PHP, c'est à dire indiquer la plage de version de
l'api sur chaque élément. Ne pas faire un article pour la version 3 et un
pour la version 3.1 par exemple.

En plus de la version compatible, on pourrait imaginer quelque chose à la
Symfony...
Exemple sur cette page : http://symfony.com/doc/current/book/controller.html
On a un petit menu pour choisir sa version de framework.
Et même mieux sur cette page :
http://symfony.com/legacy/doc/forms/1_4/en/01-Form-Creation
Là, on a un message d'alerte nous prévenant qu'il y a une documentation
plus à jour.

Sur ce dernier point, cela rejoindrait ton avis sur le fait de ne pas
ré-écrire un article sur une fonction d'une version à une autre alors que
"rien" n'a changé entre ces 2 versions données.

On pourrait faire en sorte qu'il y ait un "mot-clé" par version qu'on
attribut à chaque article...
C'est dans la même lignée de ce qui s'est fait sur spip.net pour la doc
mais n'a jamais été exploité.

Ça donnerait c.s.n/fr/apis/cvt/charger par exemple
ou c.s.n/fr/apis/sql/sql_select

Si c'est traduit, ça sous-entend qu'on ne peut se suffire d'extraire
automatiquement les données de l'autodoc pour une API, puisque celles si ne
sont pas traduisible, et que donc, l'objet qui accueille la fonction (un
article ou un objet spécifique) doit pouvoir recevoir soit un texte
décrivant chaque élément de la fonction (arguments, types, retours...) soit
avoir des liaisons ou des champs spécifiques à remplir. Le cas des liaisons
est … difficile à gérer car il peut y en avoir beaucoup, et à traduire ça
serait tout aussi casse pied. Je me demande si un format texte (ou pourquoi
pas la même écriture que le phpdoc) ne serait pas aussi bien. Ainsi on
enregistrerait le phpdoc de la fonction dans un champ de l'objet et il
pourrait être traduit, puis analysé à l'affichage donc.

D) sur l'autodoc (qui n'a pas de traduction), gère t'on différentes

versions de SPIP, si oui, comment ?

Je pense que l'autodoc est quelque chose exclusivement pour les
développeurs et que… partant de ce point de vue, il serait inutile de faire
afficher différentes versions, mais uniquement la dernière version en
développement.

Cela dit, techniquement ce n'est pas compliqué d'avoir autodoc/dev/ et
autodoc/3.0/ ...

Techniquement non plus ça ne serait pas compliqué d'avoir
- autodoc/dev/ qui aurait toutes les fonctions du monde entier
- et autodoc/3.0/ qui ne listerait que ce qui est déclaré avec @api
(resterait plus grand chose, et plein de @see seraient sans suite)

À voir…
Y a des remarques ?

MM.
______________________________**_________________
spip-doc@rezo.net - http://listes.rezo.net/**mailman/listinfo/spip-doc<http://listes.rezo.net/mailman/listinfo/spip-doc>

Le 18/03/2013 12:55, Matthieu Marcillaud a écrit :

Mais il n'a pas vocation à servir de lieu de débug ou d'entraide !

Il faudra une charte claire là-dessus, pour éviter de devoir ré-expliquer à chaque fois en détail pourquoi on a supprimé tel ou tel commentaire (ce qui arrivera sûrement).

A) que manquerait t'il pour sa mise en ligne ?

Pas grand chose, si ce n'est la question des versions, posées au début de ce fil de discussion.

B) gère t'on les traductions sur le SPIP ? si oui, comment ?

Oui, les APIs c'est de la doc technique pour tous, donc dans plusieurs langues.

Au niveau du contenu, à priori les APIs ça sera un peu comme l'autodoc mais un peu plus fourni et complet et seulement sur certains groupes de fonctions précis. Entre l'autodoc et programmer.spip quoi (et du coup il faudra sûrement revoir certains morceaux de programmer qui deviennent alors trop détaillés, trop fonction par fonction ?).

Ton idée d'écrire du PHPdoc dans un champ de texte est intéressante. On sait le parser, c'est un format connu des développeurs (car c'est eux surtout qui vont contribuer à la doc technique, ou au moins des bidouilleurs).

C) gère t'on les versions de SPIP ? si oui, comment ?

L'avantage de la méthode php.net c'est de ne pas faire trop de doublons. Mais en contrepartie on se retrouve avec un site et des listes qui vont mélanger plusieurs versions (sauf à n'afficher par défaut que les choses qui incluent la version en cours). De plus, certaines fonctions vont avoir des ajouts ou des retraits, bref pas forcément exactement le même comportement (envoyer_mail, telle fonction qui a un argument en plus, etc), suivant les versions.

La duplication comme pour les docs "livres" (programmer, etc) et la fixation des anciennes versions, permettraient d'avoir moins de choses à maintenir (seulement la version stable et la version en dev).

D) sur l'autodoc (qui n'a pas de traduction), gère t'on différentes
versions de SPIP, si oui, comment ?

Tout dépend si l'on doit faire des liens *depuis* les autres docs (les APIs et programmer, surtout).

Il serait alors bien que l'autodoc affiche la version stable par défaut (je pense que c'est mieux que dev), mais contiennent des dossiers par versions : les précédentes, celle en cours, et la dev. Pour les précédentes, je parle dans le futur, là on commencerait avec la 3.

Ainsi depuis les autres sites, on peut renvoyer vers la doc de la fonction : pour un humain c'est souvent mieux que de renvoyer vers le code source directement (sauf quand on veut montrer le contenu de la fonction évidemment). Et il faudrait évidemment que les URLs soient prédictibles pour pouvoir automatiser un peu (genre "je veux la fonction trucmuche() en version 3.1").

Bref oui je pense que c'est bien que l'autodoc soit dupliqué à chaque version, autodoc/x.y/@truc (mais tout à chaque fois, pas que les APIs, qui sont déjà autre part).

--
RastaPopoulos

Le 19/03/2013 14:46, RastaPopoulos a écrit :

Le 18/03/2013 12:55, Matthieu Marcillaud a écrit :

Mais il n'a pas vocation à servir de lieu de débug ou d'entraide !

Il faudra une charte claire là-dessus, pour éviter de devoir ré-expliquer à chaque fois en détail pourquoi on a supprimé tel ou tel commentaire (ce qui arrivera sûrement).

Possible oui.

A) que manquerait t'il pour sa mise en ligne ?

Pas grand chose, si ce n'est la question des versions, posées au début de ce fil de discussion.

B) gère t'on les traductions sur le SPIP ? si oui, comment ?

Oui, les APIs c'est de la doc technique pour tous, donc dans plusieurs langues.

Au niveau du contenu, à priori les APIs ça sera un peu comme l'autodoc mais un peu plus fourni et complet et seulement sur certains groupes de fonctions précis. Entre l'autodoc et programmer.spip quoi (et du coup il faudra sûrement revoir certains morceaux de programmer qui deviennent alors trop détaillés, trop fonction par fonction ?).

Tout à fait (pour Programmer).

Ton idée d'écrire du PHPdoc dans un champ de texte est intéressante. On sait le parser,

Oui (et non). Oui car il y a des outils pour en PHP (et j'en ai branché un dessus déjà), mais non également car ça n'a pas toute la puissance
d'une analyse globale du code par phpDocumentor. Particulièrement, @see truc() : phpdocumentor fait un lien automatiquement si truc() est une fonction qu'il a croisé dans le code qu'il a analysé, quelque soit son emplacement, ce qu'on peut plus difficilement obtenir en analysant que le phpdoc d'une fonction uniquement. Mais bon, y a un bon début déjà.

c'est un format connu des développeurs (car c'est eux surtout qui vont contribuer à la doc technique, ou au moins des bidouilleurs).

C) gère t'on les versions de SPIP ? si oui, comment ?

L'avantage de la méthode php.net c'est de ne pas faire trop de doublons. Mais en contrepartie on se retrouve avec un site et des listes qui vont mélanger plusieurs versions (sauf à n'afficher par défaut que les choses qui incluent la version en cours). De plus, certaines fonctions vont avoir des ajouts ou des retraits, bref pas forcément exactement le même comportement (envoyer_mail, telle fonction qui a un argument en plus, etc), suivant les versions.

La duplication comme pour les docs "livres" (programmer, etc) et la fixation des anciennes versions, permettraient d'avoir moins de choses à maintenir (seulement la version stable et la version en dev).

J'essaie de te suivre. Cela sous-entend des urls tel que
http://code.spip.net/3.0/fr/
http://code.spip.net/dev/fr/

Et encore
http://code.spip.net/3.0/autodoc/…
http://code.spip.net/dev/autodoc/…

Il est possible de faire un SPIP mutualisé avec chaque version par exemple, du coup, entre chaque version il «suffit» de dupliquer la bdd et de créer une nouvelle instance, par exemple «3.1» avec la bdd. Mais dans ce cas, les commentaires de la fonction envoyer_mail() en 3.0 ne seront pas au même endroit (ni sur le même site) que ceux de la fonction en 3.1. Dans ce cas est-ce que les commentaires restent ouverts pour les versions différentes de la version stable en cours, par exemple sur la 3.0 alors que la 3.1 est sortie ?

Si c'est des SPIP différents, il est difficile de faire des liens entre les sites. Si c'est un même spip pour toutes les versions, il est difficile de dupliquer une arborescence (encore que) au moment d'une nouvelle version, et de la même façon des liens entre rubriques hors traduction ne sont pas évidents à faire...

Il y a beaucoup de choses et chaque solution a ses propres contraintes et problèmes.

D) sur l'autodoc (qui n'a pas de traduction), gère t'on différentes
versions de SPIP, si oui, comment ?

Tout dépend si l'on doit faire des liens *depuis* les autres docs (les APIs et programmer, surtout).

Il serait alors bien que l'autodoc affiche la version stable par défaut (je pense que c'est mieux que dev), mais contiennent des dossiers par versions : les précédentes, celle en cours, et la dev. Pour les précédentes, je parle dans le futur, là on commencerait avec la 3.

Qu'entends tu par des dossiers ? Je ne peux pas générer 1 espace «autodoc» qui ait des relations entre les versions. C'est l'autodoc d'un lot de fichiers (un SPIP). Autrement dit, je peux faire autodoc/3.0/[docs] et autodoc/3.1/[docs] mais pas, par exemple autodoc/fonctions/propre/3.0

Ainsi depuis les autres sites, on peut renvoyer vers la doc de la fonction : pour un humain c'est souvent mieux que de renvoyer vers le code source directement (sauf quand on veut montrer le contenu de la fonction évidemment). Et il faudrait évidemment que les URLs soient prédictibles pour pouvoir automatiser un peu (genre "je veux la fonction trucmuche() en version 3.1").

il peut y avoir une api aussi code.spip.net/doc.api/3.1/propre()
ou une redirection avec htaccess (comme il y a déjà à la racine de autodoc) autodoc/@propre

Bref oui je pense que c'est bien que l'autodoc soit dupliqué à chaque version, autodoc/x.y/@truc (mais tout à chaque fois, pas que les APIs, qui sont déjà autre part).

heu si c'est tout à la fois, c'est x.y/autodoc comme présenté plus haut ?

Après si vraiment ça pose problème on peut aussi faire 2 sites différents. Perso je m'en fiche. J'avais vraiment l'impression que c'était plus logique d'avoir tout au même endroit (et apis et l'autodoc du code) mais, si ça se trouve, non !

MM.

Le 19/03/13 15:27, Matthieu Marcillaud a écrit :

Après si vraiment ça pose problème on peut aussi faire 2 sites différents. Perso je m'en fiche. J'avais vraiment l'impression que c'était plus logique d'avoir tout au même endroit (et apis et l'autodoc du code) mais, si ça se trouve, non !

Ca parait plus logique de mettre tout au même endroit, et dupliquer les bases, à mon avis ça risque de perdre beaucoup d'énergie, mais peut-être que je ne connais pas les bons arguments.
Sinon, y'a pas moyen comme sur plugin.xml pour dire que la fonction va de [2.1 à 3.2[ et permettre ainsi de mieux gérer la doc et ses différentes traductions ?

++
touti

Le 19/03/2013 15:39, toutati a écrit :

Ca parait plus logique de mettre tout au même endroit, et dupliquer les
bases, à mon avis ça risque de perdre beaucoup d'énergie, mais peut-être
que je ne connais pas les bons arguments.

Au niveau technique, la duplication est plutôt celle qui est la plus rapide à mettre en place et qui prend le moins d'énergie : on copie la base, on renomme et basta. Mais ça pose notamment la question du suivi des commentaires dont parle le dernier message de Matthieu.

Sinon, y'a pas moyen comme sur plugin.xml pour dire que la fonction va
de [2.1 à 3.2[ et permettre ainsi de mieux gérer la doc et ses
différentes traductions ?

Si, c'est ce dont parlais Matthieu dans son mail d'avant pour copier le fonctionnement de PHP.net. Mais je notais que ça pouvait impliquer des problèmes (accumuler des vieux trucs qui trainent, et des mêmes fonctions qui n'ont pas la même doc et pas les mêmes arguments suivant la version).

--
RastaPopoulos

Le 19/03/2013 15:27, Matthieu Marcillaud a écrit :

Il est possible de faire un SPIP mutualisé avec chaque version par
exemple, du coup, entre chaque version il «suffit» de dupliquer la bdd
et de créer une nouvelle instance, par exemple «3.1» avec la bdd. Mais
dans ce cas, les commentaires de la fonction envoyer_mail() en 3.0 ne
seront pas au même endroit (ni sur le même site) que ceux de la fonction
en 3.1. Dans ce cas est-ce que les commentaires restent ouverts pour les
versions différentes de la version stable en cours, par exemple sur la
3.0 alors que la 3.1 est sortie ?

Mmmmh, oui, je n'avais pas réfléchi aux commentaires.

Quand on duplique une base, la plupart des commentaires d'une fonction dans la version suivante seront toujours valables. Donc on peut les laisser dans la duplication. Dans ce cas, les commentaires de envoyer_mail() en 3.1 contiendront les commentaires écrits durant la 3.0.

Pour les anciennes versions, on peut bloquer l'accès rédac pour le contenu, mais laisser ouvert les commentaires (mais ça implique plus de modération, sur plusieurs sites). À voir peut-être suivant le volume, càd voir s'il y a vraiment beaucoup de gens qui vont ajouter des commentaires sur les anciennes versions non présentées par défaut.

Par contre ne pas ouvrir de commentaires sur la version en dev. En fait ce point m'interroge car si on duplique le site APIS pour la version en dev, on aura les commentaires du moment, mais les gens vont continuer d'ajouter des choses intéressantes sur la version stable (présentée par défaut), et donc quand la dev deviendra la stable... si on a déjà dupliqué en amont, il manquera tous ces commentaires ! Du coup, pour les APIs, est-ce qu'on doit vraiment avoir la version dev ? Ou juste au moment où la dev devient la nouvelle stable ?

Si c'est des SPIP différents, il est difficile de faire des liens entre
les sites.

Pour le cas précis de la doc du code, je ne vois pas trop la difficulté car une fois bien définies, les URLs sont plutôt prédictibles.

domaine/version/fonction

Pas mal d'ailleurs, l'idée de faire une API qui ferait des redirections permanentes.

Si c'est un même spip pour toutes les versions, il est
difficile de dupliquer une arborescence (encore que) au moment d'une
nouvelle version, et de la même façon des liens entre rubriques hors
traduction ne sont pas évidents à faire...

Il y a beaucoup de choses et chaque solution a ses propres contraintes
et problèmes.

Oui. Pour l'instant la duplication (avec URLs prédictibles) me semble la plus facile à gérer (en ayant statué la question des commentaires). Mais peut-être me trompes-je.

Qu'entends tu par des dossiers ? Je ne peux pas générer 1 espace
«autodoc» qui ait des relations entre les versions. C'est l'autodoc d'un
lot de fichiers (un SPIP). Autrement dit, je peux faire
autodoc/3.0/[docs] et autodoc/3.1/[docs] mais pas, par exemple
autodoc/fonctions/propre/3.0

heu si c'est tout à la fois, c'est x.y/autodoc comme présenté plus haut ?

Oui oui, je me suis emmêlé. En fait à priori le SPIP des APIs et l'autodoc auront toujours exactement le même cycle de vie, donc le numéro de dossier/URL est bien au début, en contenant les deux.

code.spip.net/x.y/fr/cvt/charger
code.spip.net/x.y/en/cvt/charger
code.spip.net/x.y/autodoc/

Il faut aussi se demander ce qu'il y a *sans* le numéro de version. Une redirection immédiate vers la version en cours ? Je tape "code.spip.net" dans mon navigateur, et je suis redirigé vers "code.spip.net/3.0" (mais un menu me propose les autres versions) ?

Ce dernier point vaut aussi pour les autres docs versionnées (programmer, utiliser, ).

Après si vraiment ça pose problème on peut aussi faire 2 sites
différents. Perso je m'en fiche. J'avais vraiment l'impression que
c'était plus logique d'avoir tout au même endroit (et apis et l'autodoc
du code) mais, si ça se trouve, non !

Je continue du trouver que c'est mieux si les deux sont au même endroit. On a déjà tellement de sites différents (et peut-être d'autres à venir)... Là il s'agit dans les deux cas de documenter du code, même si c'est de deux manières différentes.

--
RastaPopoulos

Le 19/03/2013 17:52, RastaPopoulos a écrit :

Par contre ne pas ouvrir de commentaires sur la version en dev. En fait ce point m'interroge car si on duplique le site APIS pour la version en dev, on aura les commentaires du moment, mais les gens vont continuer d'ajouter des choses intéressantes sur la version stable (présentée par défaut), et donc quand la dev deviendra la stable... si on a déjà dupliqué en amont, il manquera tous ces commentaires ! Du coup, pour les APIs, est-ce qu'on doit vraiment avoir la version dev ? Ou juste au moment où la dev devient la nouvelle stable ?

C'est une bonne question.
Il est aussi possible de préparer les nouveaux futurs articles sur la dernière stable, et de dupliquer la bdd au dernier moment, puis de les publier.

heu si c'est tout à la fois, c'est x.y/autodoc comme présenté plus haut ?

Oui oui, je me suis emmêlé. En fait à priori le SPIP des APIs et l'autodoc auront toujours exactement le même cycle de vie, donc le numéro de dossier/URL est bien au début, en contenant les deux.

code.spip.net/x.y/fr/cvt/charger
code.spip.net/x.y/en/cvt/charger
code.spip.net/x.y/autodoc/

Il faut aussi se demander ce qu'il y a *sans* le numéro de version. Une redirection immédiate vers la version en cours ? Je tape "code.spip.net" dans mon navigateur, et je suis redirigé vers "code.spip.net/3.0" (mais un menu me propose les autres versions) ?

Je pensais à une petite page d'accueil qui propose en gros d'aller sur la version stable, mais qui indique les liens vers les autres versions aussi.
La redirection peut aussi être jouable.

Par contre là tout de suite, ce qui m'ennuierait c'est de ne pas avoir l'autodoc de la version en dev dans cette situation. Ne serait-ce que pour vérifier les phpdoc et les erreurs qu'il y a.

D'ailleurs, je pense que les propositions de phpdoc que peuvent faire les visiteurs ne doivent se faire que sur la dev (si jamais certains en font, sait-on jamais).

Du coup, je me demande où cet autodoc serait si il n'existe pas encore de code.spip.net/dev/

Je continue du trouver que c'est mieux si les deux sont au même endroit. On a déjà tellement de sites différents (et peut-être d'autres à venir)... Là il s'agit dans les deux cas de documenter du code, même si c'est de deux manières différentes.

Peut être… cela dit 2 choses me préoccupent.

1) l'autodoc est prêt (il me semble, ou du moins dans sa plus grande partie), même s'il évoluera encore. Et j'ai
l'impression qu'on se torture l'esprit pour trouver comment résoudre un problème certes difficile, mais qui est différent encore d'une doc autogénérée.

2) il faut des énergies importantes pour créer ces documentations (autour des API et même d'autres), peut être encore plus importantes que pour remplir les phpdoc sur le code source. Je ne sais pas si on les a. En tout cas actuellement là tout de suite je ne suis pas certain. Alors du coup, faut il réellement se prendre la tête maintenant sur ce problème ? ou attendre d'avoir d'autres énergies et motivations plus tard, avec d'autres idées et d'autres solutions. Je n'ai pas spécialement de réponse. J'essaie de faire un constat. J'espère simplement que ce n'est pas moi qui décourage les gens.

Ce que je vois à long terme c'est la possibilité de sortir une partie de SPIP.net sur ce site, et une partie de Programmer aussi certainement. Là encore il faut des volontés et des énergies pour que ça fonctionne. Et personne n'est rémunéré pour le faire. Peut être en sous-traitant à des indiens on pourrait s'en sortir :slight_smile: Tel que c'est parti je le sens pas trop.

- - -

Alors oui, il faut réfléchir certainement à ce site d'API, pour qu'il ne devienne pas trop comme spip.net avec des contenus datant de mathusalem qui ne sont du coup pas très clair à la lecture au premier abord, mais est-ce si important que ça de garder une trace de tout cet historique ?

Si vraiment y a besoin de remonter dans le temps, il reste les archives internet :slight_smile: On a le droit je crois de dire : nous on choisit de ne présenter que la documentation à jour (pour peu déjà qu'on y arrive !) en s'affranchissant du passé, et éventuellement en créant un espace expliquant comment migrer (les apis) d'une version à une autre. Un peu comme fait jQuery lorsqu'ils sortent une version, ils disent ça c'est déprécié, ça faut le faire comme ça maintenant... Ça me semblerait plus… simple finalement au bout du compte.

Du coup, ça ferait un gros problème en moins. Il ne resterait que les traductions à gérer.
Et l'autodoc pourrait lui être par version.

Ça donnerait possiblement :

c.s.n/fr/api/cvt/charger
c.s.n/en/api/cvt/charger <-- là va y avoir collision l'url arbo
c.s.n/autodoc/dev/...
c.s.n/autodoc/3.0/...
c.s.n/fr/migration/3.0/ ...
c.s.n/fr/migration/3.1/ ...

...

Bonsoir,
Et Bravo pour ce Zora que je re-decouvre !
j'ai un peu de mal a suivre (prenant le train en marche): excusez si j'ai des reflexions HS

Le 19/03/2013 13:52, Ybbet Spip a écrit :

Le 19 mars 2013 13:07, Matthieu Marcillaud <marcimat@rezo.net <mailto:marcimat@rezo.net>> a écrit :

    Face à ce bel écho, je livre mes réponses :slight_smile:

    Le 18/03/2013 12:55, Matthieu Marcillaud a écrit :

        Questions en vrac :

        A) que manquerait t'il pour sa mise en ligne ?

    Ce que je pense, c'est que, c'est déjà mieux qu'avant, et que
    donc, bah, ce qui est fait et fait qu'on peut le mettre en ligne ?

C'est tres intéressant et facile d'usage,mais je garde avec bcp d'interet certains articles -rédiges- anciens de doc.spip.org, car ils expliquent bien certaines choses....
Quant à "eliminer" des indications de Programmer (lu dans un autre msg), pitié non !
C'est déja assez difficile a comprendre parfois, meme avec l'aide de magraine !

Si la doc de SPIP n'est conçue que pour ceux qui savent déjà,
       SPIP ne perdurera pas.... :frowning: :frowning: :frowning:

    B) gère t'on les traductions sur le SPIP ? si oui, comment ?

    Oui, les APIs c'est de la doc technique pour tous, donc dans
    plusieurs langues.

+1 .. si on peut !

Sur ce dernier point, cela rejoindrait ton avis sur le fait de ne pas ré-écrire un article sur une fonction d'une version à une autre alors que "rien" n'a changé entre ces 2 versions données.

On pourrait faire en sorte qu'il y ait un "mot-clé" par version qu'on attribut à chaque article...
C'est dans la même lignée de ce qui s'est fait sur spip.net <http://spip.net> pour la doc mais n'a jamais été exploité.

    l'usage complet des mot-cles est rarement utilisé (cf. aussi
    contrib..) !
    Bravo de remettre en bon usage...

        D) sur l'autodoc (qui n'a pas de traduction), gère t'on
        différentes versions de SPIP, si oui, comment ?

    Je pense que l'autodoc est quelque chose exclusivement pour les
    développeurs et que... partant de ce point de vue, il serait
    inutile de faire afficher différentes versions, mais uniquement la
    dernière version en développement.

Developpeurs... de SPIP ou plugins ?
     ou cela concerne-t-il aussi les utilisateurs avancés webmestres-codeurs ?
Je militerai pour ne pas oublier les seconds....

--
YannX

Ils y sont :slight_smile: Mais ils sont un peu périmés. Je les ai dans une rubrique «Archives» Il ne s’agit pas d’éliminer, mais de déplacer :slight_smile: La nuance est importante. Ceux qui savent déjà n’ont pas besoin de doc. Effectivement on peut. Après… est-ce réellement utile… Disons que ça concerne ceux qui ont besoin de toucher à du code PHP pour faire des choses avec SPIP, appelle les comme tu veux, peu importe. MM.