doc.spip : quel domaine, et contenu

Équipes documentation
1

J’ai plusieurs gros problèmes avec ce nouveau site :

  • Utiliser sans trop de discussion un domaine aussi générique que le mot « doc », alors que manifestement tout les sites sont de la doc (comment installer, comment utiliser, comment intégrer des sites, comment développement des nouvelles fonctionnalités, etc). On avait passé des tonnes de temps ya des années pour aboutir à des nommages relativement clairs et chacun dédié à des sous-publics précis. Si c’est pour se retrouver avec un site « doc » qui n’est absolument pas « la doc », mais bien « une doc ultra précise pour un public précis »… c’est un gros problème d’UX et de compréhension.
  • Surtout : c’est un énième site en plus, alors que ça fait des années qu’on a des remarques comme quoi personne ne sait où chercher la doc, où chercher quoi suivant quel sujet, c’est trop dispersé et bazar… et là on rajoute du bazar supplémentaire par dessus un état qui était déjà critiquable et à améliorer.
  • Il y a déjà un site orienté dévs. Que cette doc Git contienne des choses contextuelles à la migration d’une version ok, mais là on parle maintenant de nouvelles docs plus larges, qui aurait dû se retrouver sur un site déjà existant.
  • Qu’il y ait une nouvelle manière de gérer la doc orientée « devs » serait ok seulement s’il y avait un projet de migration complète de Programmer dans cette nouvelle manière de faire. Si c’est uniquement pour ajouter un site en plus par dessus l’existant : c’est un très très gros problème d’UX et de découvrabilité des contenus.
  • Pour reformuler : au niveau UX, pour les lecteurices (dont les gens déjà là, pas que les nouvelles), il est préférable de continuer à utiliser système perfectible, mais déjà connu et identifiable, plutôt qu’un nouveau système théoriquement mieux qui se sur-rajoute à l’existant, si ce n’est pas pour le remplacer totalement.
  • (Sans parler de Git VS CMS pour faire de l’éditorial qui peut/doit intégrer des images, des schémas, etc à terme, et de l’éditorial traduisible par des gens juste traducteurices. Encore un autre débat serpent de mer.)

Corollaire :

  • m’est-avis qu’il faudrait virer le domaine très récent « doc.spip », et mettre « migration.spip » ou autre chose de plus précis
  • décider collectivement quel contenu on veut dedans, et pas « au petit bonheur la chance » : est-ce que ça doit totalement remplacer Programmer (UN seul sous-site orienté devs, pas plusieurs), et dans ce cas on doit se donner les moyens de tout migrer dessus ? Ou bien que de l’aide à la migration, et donc la doc d’architecture devrait être dans Programmer V5 ?
2

Je vais répondre à quelques points donc.

Origine

Alors déjà cela fait suite à la discussion Doc migration 5.x et dépot spip/spip et notamment Doc migration 5.x et dépot spip/spip - #20 par marcimat : on a créé 2 domaines

L’objectif était double :

  • permettre d’avoir des Pages gitlab (et donc des sites statiques) à partir de doc en markdown dans un dépôt (et toujours à jour avec le dépôt) aux urls pages.spip.net/{org}/{depot} donc.
  • sur SPIP, migrer et scinder la doc d’Upgrade qui devenait impossible à gérer.

sur le nom doc.spip.net

Je ne suis pas figé sur doc.spip.net mais cela dit, au vu de la qualité de zensical utilisé derrière et de sa recherche, je pense qu’on peut y mettre un peu plus que de la doc de migration.

En tout cas je souhaite absolument conserver le fait que c’est le dépôt qui contient sa documentation technique : c’est vraiment beaucoup plus facile à gérer que de devoir aller éditer un site éditorial SPIP en préparant et modifiant des articles non publiés. Par ailleurs peu de monde maintient la doc publique des plugins à jour sur Contrib lorsqu’un plugin évolue par exemple.

D’autant plus qu’on (nous en développant) peut chercher directement dans notre IDE ce qui est déjà documenté ou pas, et aussi demander aux agents IA qu’on utilise de synchroniser les modifications apportées en même temps : c’est un gain en temps considérable qui nous permet de nous concentrer sur les problèmes techniques à résoudre avant tout, et sans omettre la doc.

Il faudra de vrais articles sur spip.net évidemment au moment de la release, mais ils pourront être des résumés ou détailler des points différents, mettre des illustrations images (dans la doc markdown, il y a des graphiques en mermaid, ce qui me semble bien suffisant déjà). Éventuellement faire des liens vers la doc statique.

sur les docs programmer.spip.net vs spip.net

Je suis très partagé sur ces documentations et sur où quoi devrait aller : ce que je sais c’est que je n’ai absolument plus d’énergie, volonté à y consacrer : je trouve cela trop lourd de préparer des articles sur un nouveau site programmer5 (mais je ne suis pas contre faire cette copie du site sur demande de qqn au besoin), de gérer des migrations d’articles de spip.net dedans ou autre : je préfères consacrer du temps à autre chose pour SPIP 5 sur le code, ce qui est déjà très énergivore (sans compter la maintenance de la 4.4 et ses releases).

Je présume que depuis toutes ces années, si des personnes avaient eu l’énergie, le temps et beaucoup de volonté pour créér des différents sites qui avaient été imaginés un jour pour découper spip.net (integrer.spip.net notamment de mémoire), cela aurait été fait. Comme beaucoup de chose, ce n’est pas aussi simple que de simplement le dire : c’est aussi un gros chantier avec toute l’histoire de spip.net que de s’occuper de ça, et c’est compréhensible que ça soit resté en status-quo.

La relation avec ce doc.spip.net (on a eu quelques difficultés à se mettre d’accord sur un nom — note que ça existait déjà et était redirigé avant sur https://code.spip.net/ — site qui pour le coup je trouve n’a guère d’intérêt) complexifie peut être encore, mais je ne serais pas choqué si une partie de Programmer entrait dedans : notamment je pense qu’il est sain d’y avoir associé un début de doc sur la nouvelle architecture et de continuer à faire évoluer cela. J’aimerais bien que ce doc.spip.net soit une sorte de référence relativement 1:1 avec le code, sur des sujets techniques effectivement, sans pour autant que ça soit le seul site ; il me semble qu’il y a de la place pour d’autres styles d’écriture (les articles de présentation de versions sur spip.net notamment)

Dans certains sites de doc, tu as une souvent des parties Recettes de cuisines, ou Études de cas qui montrent des développement plus complets, exemples de A à Z, qui seraient possiblement pertinent d’avoir, et qui a priori ne seraient pas sur ce doc.spip.net, plus éditorialisés, plus descriptifs : c’est aussi des choses qui pourraient être intéressantes d’avoir.

Bref le sujet est vaste effectivement.

3

Peut-être passer de doc.spip à technique.spip ? Ou tech.spip qui est plus i18n friendly ?

4

Notons des discussions antérieures là Documentation au fil de l'eau ?

5

Voui je disais donc déjà la même chose : c’est toujours une mauvaise chose par défaut d’ajouter des lieux supplémentaires plutôt que centraliser dans l’existant.

C’est pas pour jouer les Cassandre, c’est juste que souvent un nouveau lieu/outil c’est motivant car nouveau, on se met à l’utiliser à fond un moment, puis ça s’essouffle, et un jour on rajoute un autre lieu, et ainsi de suite. Et à la fin on se retrouve avec 50 lieux différents, chacun avec juste un peu de choses.

Dont acte :sweat_smile:

Ou tech.spip

Ça serait déjà bien mieux pour circonscrire le sujet.

Cela ne changerait bien sûr pas le problème « encore un nouveau lieu, pour les devs aussi, avec un contenu pour les mêmes gens que Programmer, parlant du noyau et des API officielle comme Programmer… mais avec pas la même chose ».

6

doc.spip.net me convient et je suis ok pour supprimer code.spip.net sans remplacement.

Ok aussi pour déplacer certains contenus de programmer.spip.net dans doc.spip.net et supprimer les programmer.spip.net. Et aussi 2/3 trucs techniques qui trainent sur www.spip.net, pourquoi pas.

-2 sites, +1 sites : ça réduit l’argument enième site en plus à néant. À -1 site, ça fait moins de « bazar supplémentaire ».

Puisque c’est de la doc technique, produite par des technicien·ne·s, qui savent ce qu’iels font, y a pas de « au petit bonheur la chance » non plus. En gros, c’est hors périmètre de la doc utilisateurice donc de la team @documentation, si tant est qu’elle a un périmètre défini.

7

Indépendamment de cette discussion (mais je préfère doc.spip à tech.spip),