[spip-dev] spip.net et le suivi des versions de la doc

Dev
1

Bonjour tout le monde

Je fais suite à une conversation qui a été initiée lors de l'apéro
hier à lyon, hier soir. Il est probable que mon raisonnement ne soit
pas allé jusqu'au bout. Donc n'oubliez pas de mettre des guillemets
lors de mes [a|in]firmation :slight_smile:

Avec Gilles et Samy principalement, nous étions d'accord pour
considérer que la doc de spip.net manquait de lisibilité concernant
les versions de SPIP.
C'est à dire, lorsqu'on recherche une information sur un élément
quelconque de SPIP, l'article présentera une grosse partie
d'historique de la vie de cet éléments. (par exemple les critères pour
les boucles)

Or on est a peu prés d'accord pour dire que si un utilisateur
recherche une info pour une version donnée de SPIP, il se moque de
savoir ce qu'il en est pour les versions précédentes et ultérieures.

Du coup on a constaté qu'on rejoignait les problématiques des sites
multilangues.

Gilles proposait une solution où on aurait une rubrique par version
qui serait dupliquée en intégralité pour la version suivante et mise à
jour au fur et à mesure.

L'avantage c'est que le site est complet pour toutes les versions
L'inconvénient c'est qu'on risque de dupliquer inutilement une tres
grosse partie de la doc.

Samy quand à lui abordait l'autre solution, c'est à dire faire une
rubrique par article et de rédiger un nouvel article dés qu'il y
aurait modification pour une version ultérieure. Et utiliser des mots
clefs pour tagguer la version SPIP concernée.

Pour ma part j'aurais eu une tendance à aller dans le sens de Gilles.

Reflexion faite, il y aurait peut être une autre solution, c'est
d'utiliser tout bêtement le systeme de versionning des articles de
SPIP dans le même esprit que SVN.
C'est à dire pouvoir tagguer un numéro de version d'un article en
fonction de la version SPIP ciblée.

Il suffirait de pouvoir affecter des mots clefs aux versions
d'article. Cela reviendrait à qualifier les versions d'article
majeures (mot clef) ou mineures (sans mot clef)

Coté public, on pourrait ainsi facilement présenter les versions SPIP
concernées par un article et acceder à la révision voulue.
Coté privé, on ne modifie pas l'architecture existante.

Je ne sais pas si cela est pertinent mais comme nous avons eu un
reflexion que j'ai pu trouver intéressante, il aurait été dommage de
ne pas la remonter.

Km

2

Or on est a peu prés d'accord pour dire que si un utilisateur
recherche une info pour une version donnée de SPIP, il se moque de
savoir ce qu'il en est pour les versions précédentes et ultérieures.

Justement, à mon sens on ne recherche pas "la doc d'une certaine
version", mais "la doc d'une certaine fonctionnalité", et c'est dans
ce sens que les évolutions d'une version à l'autre sont indiquées dans
les articles.

Pour la doc "par version", je recommande l'export PDF de la doc, qui
peut se faire une fois de temps en temps, et reste "figé"

-- Fil

3

Est-ce qu'on ne pourrait pas tout simplement en mettant une page à jour (ce qu'on ne fait pas souvent en anglais...) biffer les réfèrences à des versions vétustes.

Par exemple, ne peut on compter que tout le monde fait tourner au moins un SPIP 1.7.2 ? Et supprimer tous les "A partir de [SPIP 1.2]", "(depuis SPIP 1.3)", etc. ?

Paolo

4

S'lt

> Or on est a peu prés d'accord pour dire que si un utilisateur
> recherche une info pour une version donnée de SPIP, il se
> moque de
> savoir ce qu'il en est pour les versions précédentes et
> ultérieures.

Justement, à mon sens on ne recherche pas "la doc d'une certaine
version", mais "la doc d'une certaine fonctionnalité", et c'est dans
ce sens que les évolutions d'une version à l'autre sont indiquées
dans les articles.

Je dirais plutôt on recherche dans la doc un certaine fonctionnalité
en rapport avec la version SPIP utilisée.
Or à mon sens voir les évolutions de la fonctionnalité dans l'article
est gênant.

Ainsi on va documenter une fonctionnalité alors quelle ne répond pas à
la version de SPIP utilisée :
- soit par une évolution de la fonctionnalité même
- soit par un non existence de cette version (obsolète ou nouveauté)

Le fait de tagguer les versions des articles ajouterait une finesse
supplémentaire sur ce point sans perdre l'aspect fonctionnalité.

Km

5

Bonjour

Est-ce qu'on ne pourrait pas tout simplement en mettant une page
à jour (ce qu'on ne fait pas souvent en anglais...) biffer les
réfèrences à des versions vétustes.

On ne peut savoir à priori pour qu'elle version la fonctionnalité est
recherchée.
L'historique est là, il serait dommage de le perdre même si c'est pour
une version considérée comme définitivement obsolète.

Km

6

cam.lafit@azerttyu.net a écrit :

Or on est a peu prés d'accord pour dire que si un utilisateur
recherche une info pour une version donnée de SPIP, il se moque de
savoir ce qu'il en est pour les versions précédentes et ultérieures.

Django (framework python) a pris la démarche suivante :

http://www.djangoproject/documentation/<nom\_page> = doc de la version svn
http://www.djangoproject/documentation/0.96/<nom\_page> = doc de la version 0.96
http://www.djangoproject/documentation/0.95/<nom\_page> = doc de la version 0.95
etc

En tête de page de la version svn, on a un lien vers les anciennes versions. Quand on est sur la page d'une ancienne version, on a un lien nous permettant de revenir à la version courante (svn).

Mes 2 cents,
Nicolas

7

S'lt

Django (framework python) a pris la démarche suivante :

http://www.djangoproject/documentation/<nom\_page> = doc de la version svn
http://www.djangoproject/documentation/0.96/<nom\_page> = doc de la
version 0.96
http://www.djangoproject/documentation/0.95/<nom\_page> = doc de la
version 0.95

On rejoint donc la logique que proposait Gilles. Toutefois elle
s'éloigne de ce que remonte Fil en amenant d'abord une logique de
version avant la fonctionnalité.

Km

8

En fait tu es vraiment d'accord avec moi car en SVN la notion de
branche n'est rien de plus qu'une copie à un instant T de l'ensemble
du répertoire concerné :slight_smile:
Pour gérer l'équivalent de "liens de traduction' en "lien de version",
il faudrait un mécanisme +/- identique qui permette de passer d'un
article dans un répertoire-version à son correspondant dans un autre
répertoire-version.

.Gilles

9

> Or on est a peu prés d'accord pour dire que si un utilisateur
> recherche une info pour une version donnée de SPIP, il se moque de
> savoir ce qu'il en est pour les versions précédentes et ultérieures.

Justement, à mon sens on ne recherche pas "la doc d'une certaine
version", mais "la doc d'une certaine fonctionnalité", et c'est dans
ce sens que les évolutions d'une version à l'autre sont indiquées dans
les articles.

Ce n'est pas du tout incompatible avec une gestion de la documentation
par version, bien au contraire.
Deux aspects me viennent à l'esprit :

- D'un point de vue ergonomique, on perd en lisibilité en surchargeant
l'information utile par de l'information obsolète.
Si j'étais nouveau en SPIP, je ne comprendrais pas pourquoi la
documentation parle de fichiers en .php3, avec des modes d'inclusion
qui ne sont plus opérationnels, ou avec des filtres qui n'existent
plus car ils ont changé de nom.
Certes points de la doc parlent au présent d'éléments qui concernent
des versions passées, c'est assez déroutant.
C'est certes intéressant d'un point de vue historique, mais pas d'un
point de vue documentaire : je télécharge une version de SPIP, je
m'attends à avoir la doc qui va avec..

- A l'inverse, je suis développeur débutant, je découvre SPIP car je
dois modifier un squelette sous une version 1.8.x. Comment puis-je
faire pour retrouver les éléments dans spip.net qui ne concernent QUE
les versions antérieures à la 1.9 ? C'est quasi impossible pour un
novice, à cause des nouvelles fonctionnalités qui sont apparues, des
parties de doc qui ont plus ou moins complètement disparues, ou des
éléments pertinants pour moi qui sont ramenés à une petite note de bas
de page indiquant qu'avant ça fonctionnait comme cela.
La doc actuelle ne facilite pas du tout la maintenance des spip existants.

Ce dernier point est fort dommageable car pour de très petites
structures qui ont des besoins basiques, avec un hébergement light, et
qui n'ont pas besoin de plugins, elles ont vraiment tout intérêt à
installer une version 1.8.3 pour des raisons simples de performance.

Que les fonctionnalités soient faciles à trouver est une chose, il
faut aussi pouvoir trouver des informations qui nous permettent de
comprendre le fonctionnement d'un squelette existant : c'est toute la
différence entre la création et la compréhension d'un squelette. Il
faut à mon sens qu'on puisse avoir dans la documentation les deux
modes de navigation, clairement identifiés, avec le moindre d'éléments
parasites si possible.

Pour la doc "par version", je recommande l'export PDF de la doc, qui
peut se faire une fois de temps en temps, et reste "figé"

Je ne suis pas d'accord avec cela : même une documentation jugée comme
complète au moment de la sortie d'une version peut louper certains
éléments. Elle peut bénéficier aussi de clarification ou d'exemples
qui l'enrichissent progressivement. C'est d'ailleurs ce qui fait le
succès d'une documentation basée sur un mécanisme de wiki : chacun y
apporte sa petite contribution, un peut comme on peut le faire via SVN
sur les plugins.

C'est aussi un gros défaut que je trouve au mécanisme de documentation
actuel : je pense qu'elle y gagnerait beaucoup à être transformer en
un wiki. Les arguments valables pour l'utilisation de SVN sont
directement applicables..

.Gilles

10

Je ne suis pas d'accord car il n'y a que la page d'accès qui change
(accueil ou résultat de recherche). Ensuite, la navigation interne est
totalement transparente. Si celle-ci favorise la visibilité des
fonctionnalités de la version courante, on se retrouve dans la logique
de navigation orientée création de squelette, comme Fil l'indiquait.

Il est tout à fait possible d'avoir des pages qui n'existent que sous
certaines versions : une fois la documentation clonée pour une version
stable de SPIP (ce qui correspond à la création d'une branche), on
fait ce qu'on veut dedans : déplacement de pages, renommages,
suppression, créations, etc..

Le seul cas qui va poser un problème de gestion, c'est l'équivalent du
"merge" qui devra être fait à la main..

.Gilles

11

S'lt

Gilles :

En fait tu es vraiment d'accord avec moi car en SVN la notion de
branche n'est rien de plus qu'une copie à un instant T de l'ensemble
du répertoire concerné :slight_smile:

Content de ne pas avoir trop déformé notre conversation :slight_smile:

Je dirais oui et non, oui car effectivement l'idée est bien d'avoir
une copie à un instant T et non car contrairement à SVN, on copierait
l'intégralité du site à chaque version contrairement aux branches
(enfin les tags/) de SVN qui ne fait finalement qu'une référence à un
instant T.

C'est pourquoi que je proposais une alternative/ compromis en
utilisant des mots clefs sur les versions d'article.

Pour gérer l'équivalent de "liens de traduction' en "lien de version",
il faudrait un mécanisme +/- identique qui permette de passer d'un
article dans un répertoire-version à son correspondant dans un

autre

répertoire-version.

Je dois dire que je ne sais pas comment fonctionne en pratique les
"liens traductions", c'est peut etre une autre voie à explorer aussi.

Samy :

javais
parlé furtivement à Gilles, il pourrait être pratique d'avoir la possibilité
de "voir cet article pour la version X".

Plus généralement, lors de la consultation de la doc, pouvoir n'afficher que
ce qui correspond à une version spécifique (tout en pouvant revenir au mode
par défaut).

C'est une reponse qu'on pourrait donner avec un principe de mot clef
sur les révisions d'un article.

Km

12

Ne pas oublier dans votre réflexion, que spip.net est un site fortement multilingue : ce qui convient ordinairement à un site francophone (ou bi ou tri-lingue) est totalement à repenser sur un site comportant une trentaine de versions, qui plus est non symétriques :wink:

13

Ne pas oublier dans votre réflexion, que spip.net est un site
fortement multilingue : ce qui convient ordinairement à un site
francophone (ou bi ou tri-lingue) est totalement à repenser sur un
site comportant une trentaine de versions, qui plus est non
symétriques :wink:

Pour ma part je n'y vois aucune contrainte lié au multilinguisme :
si on a un site par version de SPIP, chacun se comporte comme le site
spip.net actuel.
une version de la doc ne parlera pas des versions futures, mais pourra
très bien intégrer des éléments passés. La création d'une version
dédiée à une version spécifique de SPIP (à partir d'une doc qui suit
la SVN) ne comporte aucune opération autre qu'une copie et donc ne
demande aucune gymnastique particulière.

.Gilles

14

Ca aura juste pour défaut de charger le serveur en dupliquant les
contenus (déja qu'il a parfois du mal...)

Ce n'est pas à la documentation de se plier aux contraintes
techniques, mais plutôt l'inverse non ?
Quand à la surcharge, elle ne consiste qu'en la création d'un autre
site. Vu que les utilisateurs iront soit sur l'un soit sur l'autre, ça
n'augmentera pas de manière conséquente le nombre de hit..
Quelle surcharge y vois-tu ?

15

Et qui écrit rédige, traduit et maintient ces 28 x 15 sites ?
Les gentils humains qui s'occupent du spip.net actuel n'arrivent déjà pas à rédiger toute la doc souhaitée, ni à la traduire et à la tenir à jour comme on aimerait. Alors il est utopique de croire que démultipler ce site apporte une amélioration quelconque !

De plus et avant tout, je ne vois pas l'intérêt d'une documentation par version. Comme le signalait initialement Fil, on recherche d'abord par fonctionnalité (en se tamponnant bien de la version).

amha

Mieux vaudrait aider à maintenir et compléter la doc existante en la réorganisant progressivement par fonctionnalités, ce que j'ai déjà amorcé dans le « guide des fonctions avancées » (voir aussi : http://www.spip.net/squelettes/brouillons/spip-plan.html qui a été discuté sur la liste SPIP-trad)

16

romy@rezo.net wrote:

Les gentils humains qui s'occupent du spip.net actuel n'arrivent déjà pas ...

A ce propos (je suis entièrement d'accord) j'ai signalé il y a trois jours sur spip-dev (c'était peut-être pas le bon endroit ?) qu'il y a un problème d'images sur spip.net

Par ex.: Captures d'écran - SPIP "Captures d'écran" ... sans image.

J'aimerais bien faire quelque chose pour y remédier, mais je crois qu'il faut faire quelque chose avec les squelettes ou bien mettre la version de SPIP à jour, ou ...

Paolo

17

> Pour ma part je n'y vois aucune contrainte lié au multilinguisme :
> si on a un site par version de SPIP, chacun se comporte comme le site
> spip.net actuel.

Et qui écrit rédige, traduit et maintient ces 28 x 15 sites ?
Les gentils humains qui s'occupent du spip.net actuel n'arrivent déjà
pas à rédiger toute la doc souhaitée, ni à la traduire et à la tenir
à jour comme on aimerait. Alors il est utopique de croire que
démultipler ce site apporte une amélioration quelconque !

Il y a erreur sur le nombre : je n'imagine pas 15 versions de
documentation, mais simplement une version par branche de SPIP.
Actuellement ça ne donne que 3 versions à mettre en place : 183, 192
et SVN
Une fois qu'une version est sortie, normalement la documentation sur
cette version ne devrait plus trop bouger.
Quand au problème de maintient à jour de la documentation, c'est
actuellement trop lourd pour motiver des lambdas comme moi à vouloir
s'y investir : il faudrait plutôt passer sur un mode "on publie
d'abord et on corrige après" plutôt que d'avoir le mécanisme
centralisé actuel

De plus et avant tout, je ne vois pas l'intérêt d'une documentation
par version.

Essaye de mettre à jour un site 1.8.1 vers une 1.8.3, tu y verras un
intérêt majeur.
L'intérêt d'avoir une documentation qui suit la SVN, c'est de pouvoir
préparer les articles au fur et à mesure de l'apparition des
fonctionnalités, et de permettre des appels à relecture générale avant
sortie "officielle" de la doc.

Comme le signalait initialement Fil, on recherche
d'abord par fonctionnalité (en se tamponnant bien de la version).

Oui mais on sait quelle version on a.
Si on recherche par fonctionnalité sans être parasité par des
informations inutiles parcequ'obsolètes ou non encore en place dans sa
version, la doc en sera beaucoup plus claire et facile à maintenir.

18

S'lt

Et qui écrit rédige, traduit et maintient ces 28 x 15 sites ?
Les gentils humains qui s'occupent du spip.net actuel n'arrivent déjà
pas à rédiger toute la doc souhaitée, ni à la traduire et à la tenir
à jour comme on aimerait. Alors il est utopique de croire que
démultipler ce site apporte une amélioration quelconque !

L'idée n'est pas demultiplier les ressources, elles sont limitées
comme partout ailleurs. Mais nous avons une problématique de
visibilité qui n'est pas nouvelle.

Si un utilisateur lambda trouve facilement et rapidement, il lui sera
d'autant plus d'être content de sa visite et de potentiellement
apporter un retour ciblé.

C'est pourquoi les 3 variantes proposées me semblent aller dans les
sens d'une simplification pour le visiteur sans pour autant ajouter
des bâtons dans l'énergie des contributeurs de spip.net

De plus et avant tout, je ne vois pas l'intérêt d'une documentation
par version. Comme le signalait initialement Fil, on recherche
d'abord par fonctionnalité (en se tamponnant bien de la version).

Là je suis loin d'être d'accord, tu cherches avant tout une
fonctionnalité qui marche avec ton SPIP. L'un amènera forcement à
l'autre et ce dans les 2 sens :
- Soit tu part d'une fonctionnalité et bien tu voudras t'assurer que
ça fonctionne bien avec ta version de spip.
- Soit tu part d'une version de SPIP et tu tiens à savoir ce qu'il a
dans le ventre.

Par exemple Les filtres de SPIP - SPIP où on aborde de la
version 1.0.2 à la 1.9.1 diverses fonctionnalités. Si on est en 1.8
(pour ne pas aller trop dans les vielles version) une partie de la doc
n'est pas pertinente.

Autrement Les balises propres au site - SPIP, où est abordé
#DOSSIER_SQUELETTE qui n'a plus lieu d'être dans la doc de maintenant
et qui oublie #CHEMIN.

Ces informations doivent exister c'est indéniable mais ces
fonctionnalités répondent bien à un instant T et à une version donnée.

Je trouve très pertinent de mettre en avant la recherche des
fonctionnalités mais on ne peut s'affranchir de la notion de version.

Mieux vaudrait aider à maintenir et compléter la doc existante en la
réorganisant progressivement par fonctionnalités, ce que j'ai déjà
amorcé dans le « guide des fonctions avancées »

C'est une très bonne nouvelle.

19

1 - Théoriquement et par défaut, un article commence par répondre aux besoins/questions concernant la dernière version stable.
2 - En avançant dans sa lecture, on a des précisions concernant les versions antérieures (ces précisions peuvent être apportées en notes de bas de page).
3 - Lorsque que ce n'est pas le cas, c'est que les gentils humains qui écrivent spip.net n'ont tout simplement pas eu le temps de mettre à jour.
Alors au lieu de critiquer, viendez corriger :wink:
Car aucune solution technique, si bonne soit-elle, ne remplacera l'humain dans l'art d'expliquer et rédiger de la doc.

20

Et pourquoi on ne documenterait pas avant la 1.8.3 ???
Quand à publier la doc d'une version de développement, je ne trouve pas ça très sérieux… (l'espace privé de spip.net sert déjà à préparer des articles sur les nouvelles fonctionnalités, mais on ne vas pas publier de la doc sur une version de dev !!)
Et encore une fois, qui a le temps d'écrire telle quantité d'articles de doc ??? Tu nous cache une fine équipe de rédacteurs dans ta manche ou quoi ???

Ceci dit, tu décris là le fonctionnement d'un site qui serait certainement intéressant, mais qui est un projet différent de spip.net