Documentation au fil de l'eau ?

Équipes documentation
1

Suite à un message posté dans une discussion sur Dev

Je m’interroge sur la façon de pérenniser des bouts de doc / d’informations, qui passent soit sur Discuter soit dans des logs de commits détaillés, et qui sont dilués dans des discussions où « enterrés » dans les historiques de commits.

L’idée serait de les copier / coller quelque part au fil de l’eau, de façon organisée (rangée par catégories / sujets) mais temporaire.
Pas un site « officiel » de doc mais un espace de travail / remise en forme collectif, avant d’intégrer ces docs dans programmer.spip par exemple.
Et cela ne concernerait que le core, pas les plugins contribs.

Exemples de « morceaux » de doc :

Un log de commit qui décrit comment personnaliser le thème ajax (cliquer sur « déplier » pour voir le log complet)

Maintenance / qualité du code :

Pour les outils :

Je ne retiens pas le carnet de Contrib, pour des raisons déja évoquées, et puis parce que à mon avis, comme les sources (discuter.spip, logs de commits) sont en markdown, il faut gérer ça en markdown aussi.

J’utilise en local Obsidian, une appli non libre mais qui gère juste une arborescence de dossiers / fichiers markdown. C’est rapide et facile à utiliser pour copier/coller ces bouts de docs.
Il existe un équivalent open source / online : https://quartz.jzhao.xyz/

On pourrait créer un dépôt git de ces bouts de docs, avec l’avantage du versionning.
Obsidian peut travailler (pull/push) sur un répo distant.

Pour la méthode

Un lien que @marcimat avait déjà posté :
https://dev.to/onepoint/documentation-chaotique-diataxis-a-la-rescousse–3e9o

Et ce lien en rapport :
https://dev.to/onepoint/doc-as-code-petit-guide-illustre-pour-mieux-se-lancer-2m2k

Que pensez vous de cette proposition ?
Avez vous une méthode / des outils de votre côté ?

2 « J'aime »
2

Perso j’aime beaucoup la typologie proposé par diataxis, et je pense qu’on devrait se baser dessus.

Ensuite j’ai toujours été favorables à avoir une doc en markdown DANS le dépot du code. Cela permet de documenter au fur et à mesure qu’on code. Et cela n’empeche pas pour les non codeurs/codeuses de proposer des améliorations de la doc, soit via un ticket soit via une PR grâce à l’interface de gitlab (et donc sans avoir besoin nécessairement de maitriser git, pour répondre à une objection qui pourrait être faite).

3

Alors une fois n’est pas coutume, spa mon habitude mais pour le coup je dirais que pour copier du contenu temporaire collectivement… bah le wiki est exactement fait pour ça non ?

Et concernant le format markdown, même s’il est le cas en entrée, bah au final c’est bien pour aboutir à des documentations permanentes qui seront… sur programmer.spip.net ou sur spip.net, donc en SPIP. Du coup qu’il faille déjà les mettre en format SPIP pour le wiki de contrib ne change pas grand chose puisqu’il faudra le faire de toute façon.

Et ça éviterait un énième outil en plus alors qu’on a déjà beaucoup (trop ?) d’outils en même temps.

Si tout était déjà migré dans un autre outil, on arrêterait Programmer etc. Mais le fait est que LA MAINTENANT le site de référence de documentation carré, didactique, avec des exemples, etc : c’est Programmer. Donc c’est ça qui doit être visé pour intégrer des nouvelles docs pour le moment, pas encore un autre endroit. C’est centralisé, tout ce qui concerne « ce qui est fourni avec un SPIP de base » pour les devs, devrait être dedans (pas un bout dans ecrire/, un bout dans prive/, un bout dans etc etc).

4

le problème c’est que le wiki d’un lieu temporaire est devenu un lieu quasi definitif…

après je te rejoints : faudrait peut être plutot proposer des articles sur programmer.spip.net tant qu’on repense pas globalement l’architecture de la doc (mais je dis bien tant que)

5

Oui mais proposer des articles sur un site de doc c’est quand on a déjà circonscrit de quoi va parler tel article, et qu’on sait où le mettre. Là le questionnement de départ de Nico c’était juste pour stocker des bouts, des morceaux éparpillés, de doc diverses « en attendant » de les regrouper/rédiger comme il faut dans un vrai article (qui pour moi pour l’instant doit bien aller majoritairement dans Programmer et parfois spip.net suivant le sujet). Et du coup bah oui pour ça le wiki sert précisément à ça : copier des trucs en vrac.

Je ne vois pas trop en quoi changer d’outil résoudrait le problème de « devient un lieu définitif » : tant que personne n’a le temps de rédiger un vrai article structuré sur un sujet précis, même dans un autre outil ça y restera pareil ! Donc ce point là précis ne me parait pas spécialement un argument pour augmenter avec encore un autre outil non ?

6

Sauf que l’expérience du wiki nous montre qu’au final ca stagne sur place, et que des gens les pensent parfois comme définitif. C’est pour cela que des articles « proposés » dans programmer.spip.net avec l’idée qu’il faille ensuite en faire un vrai article de manière très claire selon le processus éditoriale concu par spip (commentaire etc) me parait plus rassurant.

7

A déterminer :
La structure hiérarchique à adopter, à priori sous forme d’arborescence de dossiers / fichiers md.
Utilisation de #tags ? Ils ne sont pas gérés nativement par markdown/Gitlab, mais Obsidian / Quartz les gèrent.

Pour la méthode
La création de tickets sur le dépôt permettrait de noter des docs à créer / compléter.

Pour les outils :
Il y a un wiki sur Gitlab, mais c’est vraiment pas pratique à utiliser pour structure rapidement (arbo de dossiers et fichiers).

Si on créait un dépôt pour cette doc collaborative sur git.spip.net, ce serait dans spip-team/documentation

Les membres de la team Documentation y sont maintainer et ont donc tous les droits dessus, les autres membres de la commu pouvant proposer des PR.

Et quel nom lui donner ?

  • DIP, ou DocInProgress (dérivé de WIP, Work In Progress)
  • Codoc
8

1/ Le wiki c’est vraiment mal foutu pour structurer, et ça aura tendance à rester sur place, et c’est à priori lié au projet (cf point ci dessous)

2/ la doc par projets, oui bien sûr, mais rien que prive et ecrire couvrent tellement de sujets… et tout le monde n’a pas les droits dessus (core)

3/ j’en reviens donc à mon idée simple, sans autre outil : un simple dépot git organisé en arbo de dossiers / fichiers md
Dans spip-team/documentation, où les gens concernés (la team documentation) sont justement maintainers.

Et par dessus, on peut localement utiliser Obsidian pour se faciliter le travail.

Et si on veut, on peut utiliser Quartz pour publier ça de façon « web ».
Exemple fait en 2 minutes : https://quartz.lerebooteux.fr/

9

Même si j’ai peur que ça stagne autant sur un repo que dans le wiki (car il faut bien à un moment que des gens se colle à la rédaction de doc à partir de tous ces extraits), je suis pour cette option qui me semble simple et rapide à mettre en oeuvre :slight_smile:

10

Maintenant, s’il y a une autre approche / méthodologie officielle pour la documentation qui est mise en œuvre (doc centralisée par projet ?), et à laquelle tout le monde se plie, ça peut faire doublon.

Mais j’ai cité deux exemples qui me semblent caractéristiques :

  • un commit avec un log qui détaillé une feature
    → doc technique de développement
  • des messages dans discuter.spip qui décrivent le fonctionnement d’outils ou de méthodes (qualité du code, maintenance)
    → guide d’utilisation

Sur ces deux infos qui ont transité, qui est censé les ajouter à la doc ?

  • la personne qui développe / modifie une feature ?
    → en pratique, personne ne le fait.
  • la personne qui explique un sujet de fond ? et où est ce que c’est censé se retrouver ?
    → en pratique, personne ne le fait non plus.

Si on doit compter sur l’équipe documentation, il faut que ce soit un travail motivant, que ses membres aient les droits et ne soient pas freinés par des PR avec la latence de la validation, sinon c’est décourageant.

Si on doit gérer ça dans programmer.spip avec des articles « en cours de rédaction », là aussi ça va éparpiller des articles à droite à gauche dans le site, dans une structure (arborescence) qui est figée, en tout cas pas facile à faire évoluer sans discussions interminables.
Et les forums de discussion sous les articles ne sont pas du tout ergonomiques (oui, il faut être réaliste et auto-critique aussi).

Dans une arbo libre (dépot git), ça permet de tester, discuter, itérer pour bien organiser, à plusieurs., avant de proposer de déployer ailleurs (programmer.spip, spip.net dans « comment contribuer », etc…)

11

Ben dans ce cas là, autant dissoudre directement la team documentation :stuck_out_tongue_closed_eyes:

12

Est ce que tu pourrais résumer rapidement ce que tu en as retenu toi ?

13

Et si, au niveau de la documentation aussi, à l’instar de composer, symfony etc, on se modernisait un peu et qu’on utilisait les outils que tout le monde utilise aujourd’hui ?
Des sources mardown, et un générateur de fichiers statiques, basés sur un dépôt git public avec tickets et PR.

14

En ce qui concerne la doc de JS vanilla qui était me semble-t-il à l’origine des questions @placido a clairement dit qu’il ferait la doc une fois que « sera stabilisé »

15

Oui, car je suis bien d’accord sur le fait qu’une nouveauté non documentée n’a que très peu d’intérêt.

Pour le chantier JS, il y a 2 points à distinguer :

  • La réécriture de ajaxCallback.js en modules : Pas beaucoup de grosses nouveautés fonctionnelles par rapport à l’existant, mais l’effort d’avoir scindé le fichier source originel de 37kio en modules thématiques et, de surcroit, d’avoir rajouté pour chaque fonction un DocBloc de présentation, constitue déjà, il me semble, un pas dans le bon sens pour améliorer la documentation.
  • Les nouveautés inhérentes à l’usage des modules / importmap et fichiers d’initialisation : un guide pratique s’impose en effet, je dois m’y atteler.

Si des personnes curieuses - qui ont suivi un peu l’affaire - souhaitent initier la chose, quand bien même, beaucoup de points resteraient flous à leurs yeux, elles peuvent le faire (sur un pad, ou un outil idoine dont les pistes ont été évoquées ici) en posant des question dans le corps du texte, et je tâcherai d’y répondre.

Ça serait un exercice de rédaction en ping-pong intéressant et un peu plus motivant.

1 « J'aime »
16

La question de la motivation est en effet aussi importante que la question de la compétence.

Et concernant la motivation, j’avais retenu que la dimension « sociale », l’interactivité et la visibilité du travail au fur et à mesure qu’il se fait, participaient à la valorisation du résultat et donc à la motivation.

C’est ce qui avait donné le mode de construction des news du blog ces dernières années = « au fil de l’eau », de manière visible et notifiée-publiquement-en-direct comme-les-commits et avec une phase de bouclage finale dédiée la mise en forme.

17

Oui oui ça peut… mais c’est un tout autre chantier que savoir où stocker des bribes temporaires :stuck_out_tongue:

Quand je parlais d’autre outil, je voulais dire encore un autre lieu surtout, càd que ce soit dans une forge déjà là ça change rien qu’un nouveau dépôt pour ça ça fait un autre lieu encore : des contenus de docs dans programmer ET dans spip.net ET dans contrib ET dans le wiki de contrib ET dans des readme ET dans un dépôt dédié git markdown… etc, ça me semblait faire beaucoup de lieux différents, donc ça me paraissait un bon truc de pas multiplier encore et encore. Mais c’est juste une intuition comme ça.

M’est-avis que quelque soit le lieu ça ne change pas le fond : que ce soit pour gérer les morceaux temporaires, ou pour rédiger la version finale (deux choses bien différentes), faut des gens avec du temps pour ça, et un lieu commun connu. Que ce soit une rubrique spip ou un git, me semble que ça change pas foncièrement les choses.

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 un peu de choses. :stuck_out_tongue:
Peut-être que c’est dans l’ordre des choses, mais c’est mieux si on n’augmente pas le nombre d’outils/lieux, voire qu’on en supprime/fusionne non ? (enfin ça me semble un objectif utile)

(Mais comme vu plus haut, je ne dis pas que les notes en vrac devraient être dans Programmer, ça je suis bien d’accord que c’est pas conçu pour ça du tout, et les notes en vrac sont possiblement destinées à plusieurs endroits de docs différents, parfois programmer, parfois le site central, etc, donc ça doit être indépendant.)

18

Comme souvent quand on a ce type de débat cela se termine par : il faut changer d’outil parce que le monde aujourd’hui utilise un truc mieux, truc qui sera obsolète dans 6 mois. Sauf que rien ne se passe car il n’est pas simple de déployer un nouvel outil et encore moins simple d’en assurer un large déploiement.

Ce qui est vrai pour le code PHP, HTML ou autre l’est encore plus pour la documentation. Cette fameuse documentation qui avait fait l’objet d’un buzz extraordinaire il y a plus de 10 ans aux grottes pour s’éteindre quasi instantanément à la sortie de ces mêmes grottes. Nous avons tous les moyens nécessaires actuellement pour écrire une documentation collective dans les sites de la galaxie même si cela n’exclut pas une réflexion parallèle : SPIP-Contrib est parfait tout comme son inénarrable Wiki qui alimente régulièrement de solides passes d’armes entre ses défenseurs et ses détracteurs (clin d’œil à @JLuc).

Le problème de la documentation et, particulièrement de celle qui est l’objet de ce débat, est la façon dont on prend le sujet. L’outil n’est pas en cause ici, mais la méthode.
Nous faisons toujours la même erreur de considérer que pour créer une documentation aboutie à plusieurs il faut en passer par une phase brouillonne où chacun pose sa pierre comme il l’entend, où il l’entend et pour qui veut l’entendre. C’est, à mon avis, faux et surtout contre-productif car cela n’aboutit jamais comme on peut le voir sur le Carnet qui en est l’expression la plus évidente quand aucune bonne volonté ne reprend le sujet globalement à son compte (le carnet ayant une vocation de réceptacle temporaire).

En effet, une fois cette masse d’informations mises à disposition de tous, chacun va y trouver sa réponse, plus ou moins complètement, plus ou moins difficilement et, on en restera là, le plus souvent.

Je pense qu’il faut faire autrement et se poser deux questions préalables pour un tel chantier :

  • une documentation pour qui ?
  • et suite à la réponse, quelle table des matières envisagée, table qui peut aussi s’enrichir petit à petit.

Une fois cette organisation définie, le fait de déposer un bout de documentation est déjà guidé, voire cela guide aussi le rédacteur dans son écriture et, tout le monde sait où l’on veut aller. C’est également plus motivant de voir qu’une partie du chemin est faite. En outre, il faut expliquer la base, les concepts sous-jacents et ne pas faire qu’un manuel utilisateur.

Je suis convaincu qu’une documentation sur ce sujet structurant (et d’autres d’ailleurs) est indispensable surtout pour attirer de nouveaux mainteneurs : sans documentation les mainteneurs actuels auront beau jeu de se plaindre car il ne seront jamais remplacés ni aidés (ou alors ce serait un vrai coup de bol). D’ailleurs, si on regarde la documentation (technique), les plugins sont assez largement documentés même si c’est assez inégal, mais la partie la moins bien documentée reste spip et les plugins-dist (le PHPDoc ce n’est pas de la documentation au sens où on l’entend ici). C’est à mon avis une cause de la difficulté à rentrer dans le code de SPIP et à l’améliorer.

19

L’essentiel est dans la « Matrix » diatexis pour moi, qui typologise 4 types de doc avec 4 buts différents et cette information importante : un document ne doit traiter que d’un seul type de doc.

Il y a ensuite des conseils pour faire un audit de l’existant et avancer vers cela, mais c’ets encore un autre problème par rapport à ton sujet initial.

20

Je suis allé faire un tour sur Diataxis : rien de révolutionnaire mais du bon sens auquel j’adhère. Je pense que si on faisait un audit de la documentation la balance ne pencherait pas vers le concept qui de mon point de vue manque cruellement pour aider dans le maintien de spip.

A savoir aussi que sur Contrib avec @rastapopoulos on a défini une typologie d’article, à savoir, actualité, conception et utilisation. Rien n’empêcherait de développer ce type pour intégrer tous ceux de Diataxis et permettre ainsi une autre vision de l’information incluse comme on l’avait un peu imaginé lors des grottes avec le portail SPIP.

Mais pour revenir aux outils et donc aux emplacements multiples, Diataxis n’y répond et je dirais même qu’il pousse à l’éviter sauf à avoir un portail qui regroupe les différentes contributions.
A cet égard, en passant une journée entière à catégoriser 65 plugins sortis d’un coup après leur « réhabilitation spip 4 », je me suis aperçu que les readme foisonnent au détriment de Contrib.
Il serait intéressant d’avoir un mécanisme sur Contrib pour intégrer le readme dans un article automatiquement en se servant de la catégorie et du préfixe du plugin (utilisation de Show Readme) et donc d’accéder à la documentation sans aller voir la forge. Cela bien entendu dans l’optique de pérenniser Contrib en tant que portail de la documentation des plugins.