Note pour mémoire : mettre à jour la doc sur spip.net :
https://www.spip.net/fr_article3367.html
https://www.spip.net/fr_article4867.html
+ créer un article spécifique pour la balise #PAGINATION ?
Comment assurer un suivi des documentations à créer et compléter ?
Là tu postes un mémo sur spip-dev.
Ces 2 derniers mois, j'ai tagué les notifications de certains commits
en local dans mon dossier thunderbird avec un tag "todo_doc" et un tag "done_doc".
C'est très léger mais c'est mal partageable :
je peux juste exporter la liste non cliquable des titre-date-auteurs,
cf il y a 8 jours : spip.pastebin.fr/88140 et http://spip.pastebin.fr/88139
Alors comment gérer collectivement le suivi des besoins de documentation ?
Bientôt peut être pourra t on commenter les commits (https://github.com/go-gitea/gitea/issues/4898)
et alors on pourra ajouter y glisser des motclés doc_todo et doc_done
(mais encore faudra t il pouvoir y faire une recherche dans les commentaires de commits, pour les retrouver...)
Sinon voyez vous qqchose ? de léger si possible.
Qq pistes : transférer sur la liste spip-redac les mails de notification de commit avec un besoin de doc (accessible pour les inscrits à cette liste) ; des tickets sur programmer.spip.net ; les forums privés sur spip.net (en étendant le droits d'accès au suivi des commentaires)...
JL
Il y a déjà un tracker "documentation" sur les tickets du core exprès pour ça : as-t-on besoin d'ajouter un autre système en plus ?
Quand c'est pour documenter un truc qui avait déjà un ticket, il suffit de changer le tracker *et le laisser ouvert* (ne pas fermer juste parce qu'il est résolu au niveau du code s'il faut encore le documenter).
Et pour ce qui n'avait pas de ticket (ça arrive mais plus rare), créer un ticket exprès.
Hop,
Dans mes listes synthétiques d'il y a 8 jours,
il y avait 29 lignes de doc_todo et 10 lignes de doc_done.
Vous imaginez autant de tickets dans le trac ?
Je n'ignore pas ce tracker mais je ne l'ai pas trouvé adapté
... de même, probablement, que Nicod qui a posté ici son mémo ?
ou que Peetdu qui poste un forum "penser à documenter ce nouveau filtre nomdufiltre"
sous un article de spip.net, où malheureusement il est inretrouvable ?
Créer un ticket dans trac est plus lourd et plus engageant
que juste dresser un flag aide mémoire "ce commit induit un travail sur la doc".
Notamment en raison de l'identification très éphémère qu'il faut vite renouveler
et aussi car la gestion y nécessite ensuite l'intervention ou les interventions d'un admin
pour valider la fermeture du ticket.
Or les admins sont en nombre restreints et ont déjà bien d'autres choses à faire
notamment relire et valider les nouvelles documentations et leurs modifs !
Le trac peut bien servir pour des méta-rapports de todo_doc
par exemple "Créer une doc sur les classes du framework CSS SPIP".
Car sur ce sujet il y aurait des trucs à discuter avant de s'y coller.
Mais on ne voudra pas créer un ticket pour chacun des commits
qui introduit une nouvelle classe css ou en modifie une...
Alors il faudrait rassembler en commentaires dans un meta-ticket ?
Ça marchera bien ainsi,
mais on aura pas de vision synthétique de ce qui reste à faire
et de ce qui a été fait.
Alors en l'état je vois plutôt 2 outils :
- un framacalc - solution pas encore évoquée - serait à la fois plus léger à tenir
et plus efficace pour tout ce qui nécessite juste un mémo et pas de discussion.
- ou un bugtracker dédié, avec des droits adaptés.
JL
Re,
Il y a déjà un tracker "documentation" sur les tickets du core exprès pour ça
Tout est là https://core.spip.net/projects/spip/issues?set_filter=1&tracker_id=4
Dans mes listes synthétiques d'il y a 8 jours,
il y avait 29 lignes de doc_todo et 10 lignes de doc_done.
Vous imaginez autant de tickets dans le trac ?
Tu peux t'organiser comme ça t'arrange, les outils sont "flexibles", un ticket documentation qui recense toutes tes todos peut aussi faire le job.
Je n'ignore pas ce tracker mais je ne l'ai pas trouvé adapté
... de même, probablement, que Nicod qui a posté ici son mémo ?
ou que Peetdu qui poste un forum "penser à documenter ce nouveau filtre nomdufiltre"
sous un article de spip.net, où malheureusement il est inretrouvable ?
Justement, ça montre bien l'intérêt de centraliser quelque part, après si vous souhiatez utiliser un autre outil que le tracker officiel qui est connu de tou⋅tes, c'est vous qui voyez 
Bah… OUI… puisqu'ils existent *déjà* pour la plupart !
Relisons : comme déjà dit, une grosse partie de ta liste, concerne des évolutions *qui ont déjà un ticket* !
Donc à aucun moment il ne s'agit de créer ex-nihilo 29 tickets. Seulement passer les tickets déjà existants en "documentation", surtout *en ne les fermant pas* (donc les devs, cédric, b_b, moi, etc, doivent aussi penser à ne pas fermer les tickets quand une évolution nécessite de la documenter).
Et ensuite seulement certains ajouts ont été faits sans qu'il n'y ait eu de demande, de ticket avant. Et là oui il faudrait les créer en plus, mais il ne me semble pas que ce soit la majorité, non ?
Après si vraiment tu veux une page genre *texte libre* en "liste à puces" ou "liste todo/checklist" qui récapitule tout : il suffit de créer UN ticket "Suivi de la documentation" qui liste les autres tickets à documenter (et parfois des lignes sans lien vers des tickets quand il n'y en avait pas).
- Un jeu de class .label-(none|inline|inline-block|block) [3316] (lien vers le ticket) + 123456abc (lien vers le commit)
- Autre truc [1234]
Et on peut même lier vraiment aux tickets (pas juste lien dans le texte libre mais vrai liaison)
Ou au pire une page "Suivi de la documentation" du wiki, sur contrib, avec une liste de todo. Dans les deux cas pas besoin d'un outil externe supplémentaire, avec un lien qu'on ne saura pas où retrouver.
Possiblement en activant le plugin Todo (qui est déjà là mais en inactif) : https://contrib.spip.net/Todo
Mais pour moi ça serait vraiment en dernier recours, car ça fait vraiment caché bidouille dans le wiki, alors qu'on a des tickets pour les tâches à faire.
Vous imaginez autant de tickets dans le trac ?
Bah… OUI… puisqu'ils existent *déjà* pour la plupart ! Une grosse partie de ta liste, concerne des évolutions *qui ont déjà un ticket* !
Donc à aucun moment il ne s'agit de créer ex-nihilo 29 tickets. Seulement passer les tickets déjà existants en "documentation", surtout *en ne les fermant pas* (donc les devs, cédric, b_b, moi, etc, doivent aussi penser à ne pas fermer les tickets quand une évolution nécessite de la documenter).
Ça semble une bonne idée !
Les devs sont ils d'accords pour cette évolution de l'usage du gestionnaire de ticket ?
Et ensuite seulement certains ajouts ont été faits sans qu'il n'y ait eu de demande, de ticket avant. Et là oui il faudrait les créer en plus, mais il ne me semble pas que ce soit la majorité, non ? > Après si vraiment tu veux une page genre *texte libre* en "liste à puces" ou "liste todo/checklist" qui récapitule
tout : il suffit de créer UN ticket "Suivi de la documentation" qui liste les autres tickets à documenter
C'est surtout qu'il faut de la légèreté donc pas envie de créer un ticket par truc à commenter qui n'a pas déjà son ticket. Et pour un ticket collectif de doc, le texte n'étant pas éditable il faudra utiliser les commentaires pour le suivi (done) ou pour en ajouter, de manière asynchrone donc dans le désordre et avec un bilan difficile à extraire. Bof.
Ou au pire une page "Suivi de la documentation" du wiki, sur contrib, avec une liste de todo. Dans les deux cas pas besoin d'un outil externe supplémentaire, avec un lien qu'on ne saura pas où retrouver. > Possiblement en activant le plugin Todo
Un calc est mieux adapté qu'une page wiki et plus facile à éditer que le texte pour le plugin todo.
Pour retrouver un calc (ou une page du wiki) on peut créer un ticket qui contient juste le lien vers ce calc,
et la description de son thème si c'est un calc pour doc_todo thématique.
Il se dessinerait donc 1 piste à 2 voies :
- l'évolution de l'usage de trac avec une étape "doc" avant le "fermer" du ticket
- un calc, avec un ticket aide-mémoire = lien depuis le trac
(ou plusieurs calcs thématiques chacun avec un ticket aide-mémoire-lien depuis le trac)
JL
Mais je n’arrive pas à croire à un outil comme un framacalc non intégré au suivi déjà existant, déjà riche en possibilités.
Lors de la préparation de la sortie de SPIP 4 j’ai vu 3 sortes de besoins de documentation :
- couverts ou à couvrir sur spip.net
- couverts ou à couvrir sur programmer.spip.net
- non couverts par spip.net ou programmer, ou de manière peu satisfaisante, ou « ailleurs », et qu’il serait bien de mieux satisfaire d’une manière ou d’une autre (par exemple : framework html css )
Et en prime, certaines de ces documentations sont aussi amenées à figurer dans un release log. Ça fait 3 destinations exclusives l’une de l’autre + 1 qui peut s’ajouter aux 3 premières.