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 ! 
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
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
