Collaboration sur la Documentation

Groupes de travail
1

Je crois qu’on a tous besoin de doc, et que nous sommes tous en train de réinventer l’eau chaude de notre coté :slight_smile:

Les docs de chatons que je connais:

Comme d’hab, c’est un peu triste mais la diversité amène de la résiliance il parait, donc, on commence à être bien résiliant sur la doc :wink:

Je lance une idée en l’air, un joli yakafokon, perso, j’ai pas le temps, mais j’aimerai bien l’avoir… et je me dis que peut-être une personne s’ennuie? Et ce serait un beau projet :wink:

J’ai des intuitions, et une approche très tech, il faudrait d’autres compétences autour de la table pour bonifier cela.

Besoins ?

En premier lieux, je pense qu’il faut plus de meilleur UX et moins de doc. (Une UX, c’est comme une blague, si il faut l’expliquer c’est qu’elle n’est pas bonne)

Je pense qu’il faut 2 entrées, usage et outils:

  • je veux faire une réunion visio
  • comment créer un lien jitsi, comment créer un évènement dans l’agenda Nextcloud

Je pense qu’il faut que la doc contienne des capture photo/gif des logiciels avec les couleurs de l’organisation.

Je pense que le mieux est que la collaboration sur les docs des outils se passe upstream, donc en anglais.
Il faut donc de jolies automatisation pour traduire.

Possibles solutions ?

En terme de solutions techniques, ce que j’entrevois, c’est:

Upstream, on écrit des bouts de doc (des partials?) qu’on peut tous traduire et réutiliser dans nos docs, à nos couleurs.

On utilise des logiciels d’automatisation de navigateurs pour prendre des captures photos/vidéos pour la doc. Ces scenarios en code sont aussi upstream pour augmenter la collaboration.

Enfin dernier point, en terme de porte d’entree au support, j’imagine un joli formulaire de recherche qui permet de chercher la doc locale, la commu Nextcloud fr et le forum de support IndieHosters par exemple et qui arrive en terme de UX à faire comprendre ou ce serait le meilleur endroit ppur avoir sa reponse.

Bref, une lettre au pere noel pour la guilde de la documentation.

On en reparle à l’occase!

Bonne soirée!

2 « J'aime »
2

mais dis donc ! T’es encore au boulot ! :upside_down_face:

Pis tu m’as piqué mon idée ! je voulais faire un post sur le forum pour la même chose.

Un gros appel à mutualisation et à travail en commun autour de la doc Nextcloud. Pour voir ensemble qu’est ce qu’on pourrait faire pour faire grossir Les Communs :slight_smile:

1 « J'aime »
3

Je ne comprends rien à cette phrase et je trouve dommage qu’on mette en place un système qui fait que celleux qui comme moi n’ont pas de bagage technique (ou qui ne parlent pas anglais) ne pourront pas participer à ce travail.

1 « J'aime »
4

Rigolo, je copie/colle le CR d’une réunion improvisée éclair entre moi et @GautGaut sur un sujet proche.

Réunion spontanée de documentation - Lundi 20 Février 2023 à 19h30

Présent⋅es :

  • ljf
  • gaut

On a fait cette petite réunion pour être plus efficace que le chat.
Contexte: Chez ARN on a une section de notre site qui n’est pas encore ouverte ni mise en avant, à savoir la section educpop qui rassemblerait :

  • ce qu’on fait en atelier Halte à l’Obsolescence et au Pistage
  • des tutoriels de découverte et d’utilisation d’outils/services Etherpad MyPads
  • du contenu théorique…
    • comment demander une intervention

On pense que pour que ça tienne dans le temps et que ça soit pas obsolète il faut:

  • pouvoir participer très facilement (on pensait à du markdown WYSIWYG + inscription totalement autonome) : le dokuwiki actuel (arn ou chatons) ne convient pas en l’état.
  • mutualiser

L’idée qui est revenu (car on en avait déjà parlé) pourrait être de proposer des tutoriels et de les rendre paramétrables avec les infos des chatons.

On a discuté de 2 approches:

  • une approche centralisée dans un outil pour tout le monde (à l’échelle de CHATONS et/ou de YunoHost). Par exemple, on pourrait avoir doc.chatons.org et avoir la version personnalisée avec les paramètres d’arn avec https://doc.chatons.org/?chaton=arn . Une partie des infos pourraient être prise depuis les fiches properties (ou autre chose si c’est l’approche YunoHost qu’on retient).
  • une approche décentralisée, on fork les doc des autres par exemple avec yeswiki ou alors chaque structure auto-héberge un dépot commun…

La solution est peut être de proposer les 2.

A noter qu’on ne connaît pas d’outils qui convient vraiment.

On reste persuadé que le gros du boulot c’est la rédaction et non le fait de transformer ça en gabarit et de trouver une solution technique pour remplir les « trous ».

On avait qu’1/2 heure donc on s’est arrêté là.

1 « J'aime »
5

Désolé, j’avais prévenu que j’avais un trope technique :slight_smile:

J’ai essayé de séparer mon propos en requirements/besoins et solutions technique.
Et je pense aussi que ce serait une bonne chose que les utilisateurices et écrivain·e·s de doc.
Ainsi, je pense qu’il est désirable que les personnes qui veulent écrire de la doc écrivent leur liste de souhaits, et que nous les techs, arrivions ensuite pour vous aider à le mettre en place d’un point de vue technique.

Upstream en language tech désigne dans le système git (là où on dev aujourd’hui en général) la source « universelle » des changements. Pour Nextcloud, cela veut dire ici pour peertube, c’est là.
Donc ce que je veux dire, c’est que je pense que cette collaboration de doc doit se passer au niveau du logicielle (la doc Nextcloud doit être fait à coté du logicielle Nextcloud).
Et donc, je pense que cela implique que ce soit fait en anglais.
Mais si dans les chatons, on dit qu’on a un super projet de doc, qu’on fera d’abord en français, puis traduit en anglais et autres, ça me va :slight_smile: (Je sais pas c’est quoi le plus simple, techniquement, j’ai l’intuition que ce sera plus simple en Anglais à coté de Nextcloud, mais si c’est pas moi qui écrit la doc :upside_down_face: ou en interlingua il parait que c’est mieux que l’esperanto :wink: cc @hrenard :wink: )

Les partials ou includes, cela veut juste dire qu’il faut éclater la doc en petit bout. Et donc imaginons, nous avons un petit bout comment créer un évènement sur l’agenda Nextcloud, et comment créer une salle visio dans jitsi, alors, nous pouvons faire un doc « usage » comment organiser une réunion en visio en appelant ces 2 bouts pour les mettre sur la même page.
(C’est une idée comme ça, je sais pas si elle est bonne)

6

belle synchronicité ljf !

Moi j’avais la version skateboard encore en dessous.

  • Soit on se réparti les trucs, et ensuite chez chacun d’entre nous, on fait pointer vers les autres pour telle ou telle partie.
  • Soit on centralise chacun ce qu’on a fait et on dépose sur un pad/forum son/ses liens, et on peut venir chercher et piocher dedans à sa guise pour partager le lien sur son site. A charge de chacun de checker les différentes documentations chez les autres pour choisir (ou pas) celle qui complète le mieux la sienne.

A l’heure actuelle dans notre doc quand on ne l’a pas fait nous même, on fait pointer vers le lien chez Nextcloud par exemple. Ca ne me semble pas incohérent de dire « nous on l’a pas fait. Mais nos collègues du CHATONS X oui, pour la trouver c’est par ici ».

J’aime ce côté organique, non standardisé (mais je suis pas informaticienne) et qui montre tout un écosystème et les univers de chacun.e.s

2 « J'aime »
7

Concernant l’implication de indiehoster (@pierre @AnneSo) sur la thématique, tu dis que vous n’avez pas d’énergie/ressources du tout ou que vous ne voulez pas leader la thématique :

Supports de (auto-) formation faciles à créer, améliorer, maintenir, partager, réutiliser, publier, collectivement

Pour rebondir sur la remarque d’ @Angie je vois deux sous-problèmes :

  1. créer, améliorer, maintenir, collectivement trouver les meilleures doc’, en faire un best-of, les standardiser point de vue rendu (jolie doc’) et technique (syntaxe commune)
    • Cela doit pouvoir être fait facilement par des personnes non techniques
      → Il faudrait commencer par définir une procédure de contribution (une documentation sur la documentation)
  2. partager, réutiliser, publier : mettre en place une architecture technique centralisée, fédérale ou distribuée
    • YesWiki avec BDD partagée ? Git ?
    • Contenus rédigés en Markdown ?
      → J’ai déjà écrit un mail à YesWiki pour savoir ce qui était possible

Je veux bien animer un groupe de travail sur 1. En effet, niveau pro je réfléchis à comment rationaliser la création de contenus pour un réseau de FabLabs.

Concernant 2. c’est @ljf et @pierre qui semblent avoir les compétences pour pousser la thématique. Ou quelqu’un d’autre veut se dénoncer ?

Et puis pour jouer un peu les modérateurs, avais-tu fait une recherche sur le forum CHATONS avant de poster ? J’avais déjà posté sur une méthodologie commune pour la création de documentations. Et j’ai fait un état de l’art
Les posts au sujet de la doc’ ne manquent pas…

1 « J'aime »
8

Bonjour à tous.

Je suis une pauvre ressource, mes journées sont déjà beaucoup trop courtes. Mais la mise en commun de la documentation est un sujet qui m’intéresse. Dans ce qui précède, je suis séduit par divers aspects :

  • l’utilisation d’un Wiki ; cela me semble facile d’utilisation et beaucoup plus pérenne que des liens croisés vers des Pads ;
  • la création d’un tronc commun qui puisse être augmenté et personnalisé par chaque chaton.

Donc, je vous lis pour le moment, j’apporterai mes commentaires si je trouve le temps, et je participerai au mieux si quelque chose commence à se construire.

2 « J'aime »
9

Hello @GautGaut , je n’ai pas vu passer de mail pour YesWiki à propos du Markdown dans YesWiki, à moins que c’était toi sur cette issue : Markdown default support · Issue #1061 · YesWiki/yeswiki · GitHub ?

En tout cas connaissant un peu YesWiki, je me sens légitime pour répondre : concernant la compatibilité Markdown, c’est encore partiel cf. Test YesWiki : Markdown mais c’est prévu d’être total.

J’aime bien l’idée de mutualiser nos efforts et de trouver un standard permettant un partage de petits bouts, d’adaptations à certains contexte, mais de mon vécu, la dette « doc » est encore plus difficile à gérer que la dette technique sur du code, car c’est difficile de se synchroniser entre dev et contributeurices à la doc.

Pour yeswiki, on a transféré la doc qui était sur le wiki dans des pages mélangées à d’autres infos, vers le code source yeswiki avec un dossier contentant des fichiers md appelés par docsify, afin que la doc suive plus facilement les changements dans yeswiki et soit adaptée à la version installée (et disponible hors ligne avec le code).

Le principal travail était plutôt un travail d’animation de la communauté, avec des visios sprint de doc, où l’on mettait les fichiers md sur hedgedoc pour de l’édition collaborative temps réel, puis des personnes à l’aise avec git modifiaient les fichiers à la fin.

Je me dit que si dans un premier temps, on avait à minimum un standard généralisé pour l’écriture des docs, par exemple markdown, et idéalement des dépôts en git pour suivre les forks, ca serait déjà bien, car c’est facile d’en récupérer des bouts à la main, et on est de toute façon toujours à adapter la doc à notre contexte, avoir des graines d’information de doc totalement génériques me parait difficile à faire.

PS: voila le résultat actuel pour la doc: Documentation

3 « J'aime »
10

Pour ma part, il me semble qu’écrire une documentation ne soit pas une « tâche non qualifiée ». Autrement dit, la réussite du projet ne tient pas qu’au nombre de personne qui travaillent dessus, mais aussi à « la qualification » des contributeur-ices.

À ce sujet, j’ai deux ressources à partager : Diataxis et le guide de contribution de StaticCMS (inspiré de celui de Kubernetes).

Diataxis est vraiment le plus important des deux ressources, car il oblige à se poser la question de l’objectif du texte que l’on va écrire : est-ce un tutoriel, donc pour objectif de transmettre du savoir ? où un guide étape par étape pour réaliser une tâche ? une explication des concepts sous-jacents, des abstractions, pour avoir une compréhension globale ? ou une référence, qui vise l’exhaustivité, et couvre en détails tous les aspects du logiciel ?

diataxis
diataxis1802×1008 47.6 KB

Ci-dessus le résumé des points précédents, mais Diataxis rentre ensuite dans le détail de comment écrire un tutoriel, comment écrire un guide, quelles questions se poser, etc.

Et pour revenir sur la mise en commun, si il y a un « cadre commun » pour écrire de la documentation, alors il sera peut-être plus simple aussi de partager ces bouts de documentation. Et des copier-coller à droite à gauche pourrait suffire dans un premier temps ^^

4 « J'aime »
11

Pour rappel, nous avons déjà partiellement listé (et appelé à le faire) les liens vers les docs des chatons sur le wiki du collectif, dans la partie Les outils du télétravail. On trouve aussi sur les outils présentés une liste de tutoriels d’utilisation. Certes, la liste des outils présentés n’est pas complète, mais si déjà on pouvait y faire apparaître toutes les docs existantes, ça serait chouette.

On a aussi des liens vers les docs utilisateurs dans toutes les fiches services.properties qui sont sur stats.chatons.org. D’ailleurs, @cpm, peut-on faire facilement un export du champ service.guide.user de toutes les fiches qui l’ont complété ?

3 « J'aime »
12

Je ne comprends pas trop pourquoi je me retrouve taguée dans ton message, alors que clairement tu ne rebondis pas sur mes propos et tu ne t’adresses pas à moi.

13

En fait ma première phrase était une question (j’ai oublié le point d’interrogation) sur la volonté d’implication d’indiehoster, donc question à toi et @pierre . Est-ce vraiment un yakafokon comme il dit, ou l’un.e de vous est-il prêt à investir du temps ? Si oui sur quels aspects?

Perso je vais proposer le « cadre commun » évoqué par @quentin (sans lire tes sources j’avais classé mon état de l’art à peu près comme ça), que je pense être basé sur Markdown. Je copie-colle donc ici ce que j’ai commencé à écrire à mon taf pour expliquer comment écrire et convertir de la doc’ en Markdown. Avis aux contributions ou discussions dans le chat du pad.

14

J’ai commencé à lire Diataxis, c’est chouette. Puisque ça en parle, j’en profite pour faire un big up aux tutoriels :point_up: !
Avec la doc CLUB1 on a une section tuto qui est très sympa à écrire avec les membres. Ça permet de rester factuel et précis sur le reste et ça fait des petites aventures, genre des quêtes à accomplir : c’est excitant !

On a aussi exploré la fonctionnalité Glossaire, qui permet de faire un tampon entre la doc et wikipedia pour pas que ça soit trop rude d’être jeté direct dehors.
Côté outil, on utilise Sphinx (Markdown +Rst) et on profite de la version PDF imprimable en Latex.
→ article qui présente la mise en place de la doc

Concernant la mise en commun, c’est vrai que c’est un casse tête vu la diversité des façons de faire et des configs. De notre côté on a pas trop de NextCloud ou trucs dans le genre, donc moins en commun facile. Par contre quand on s’attaquera à la doc de Matrix, c’est clair qu’on ira piocher des idées chez les autres CHATONS.

3 « J'aime »
15

Oui, absolument :sunglasses: Il suffit d’aller sur la page des exports et par exemple télécharger le fichier .ods de la ligne services puis l’ouvrir dans un tableur (LibreOffice…) et alors les informations sont dans la colonne K :smiley_cat:

3 « J'aime »
16

Bonjour! Désolé, je n’ai pas encore fait de post de présentation

J’adore cette notion de « quête » @vincent-peugnet pour approcher les ressources et/ou l’apprentissage !
Le monde de la sécurité informatique part lui en capture de drapeaux pour s’exercer :video_game:

Et si le journal de quêtes apprenait à nager ? :thinking:

Infographie-DigComp
Infographie-DigComp900×639 300 KB

Extrait de « DigComp | cadre de référence européen des compétences numériques »

Ici pour le Français :
https://oce.uqam.ca/digcomp-cadre-de-reference-europeen-competences-numeriques/
là
https://joint-research-centre.ec.europa.eu/digcomp/digcomp-framework_fr
pour l’anglais :roll_eyes:

DigComp + Framework Diataxis (cc @quentin) + saisie de contenu formalisé à inventer (cc @pierre @Angie)

Saisie de contenu à formaliser :

  • documentation collaborative (orienté diataxis)
    • tutos
    • explications
    • références
    • fiches pratiques
  • demande de support
    • bug (joindre screenshots, logiciels, versions, …)
      • Épingler les problèmes connus (incompatibilités, en cours de résolution…)
    • aide (‹ Je cherche à faire › ; ‹ J’ai donc entrepris › ; ‹ Je n’arrive pas ›)
      • résolution des demandes (Voir telle fiche pratique, Ajout d’explications)
  • scénarios qui parcours des tutos et fiches pratiques
  • … ?

Peut-être des liens à faire entre une question de support, une question d’auto-évaluation et une question de FAQ ? Qui vont produire des explications, fiches pratiques, références et tutos ?

Aussi, m’est d’avis qu’il est urgent d’entreprendre autre chose que beta.gouv.fr/startups/pix

On comprends vite le malaise avec un namespace pareils /startups.

Svp :face_holding_back_tears:, un groupe de travail nager . chatons . org

@pyg C’est Pierre-Yves de Framasoft ?
Je serai preneur de ton avis sur ce ‹ service public › : ‹ produit pérennisé ›,‹ incubé › puis ‹ sponsorisé › (rien que ça!) par nos ministères :face_with_raised_eyebrow:

image
image1458×806 133 KB

Archivé sur la wayback machine pour les sciences sociales du futur

Chez Framasoft, vous pensez ouvrir des groupes de paroles pour CNFS désabusé.e.s/démissionné.e.s ?

Rappelons que Pix :nauseated_face: est/va devenir un parcours obligé dans les écoles si j’ai bien suivi ? (pour les précaires itou)

1 « J'aime »
17

Quel entousiame :slight_smile:

On discutait doc avec @reminec et je me disais, il faut que je lui communique ce que j’ai en tête à ce propos, et plutot que ce soit dans un chat privé, ici, c’est beaucoup mieux!

Tout d’abord merci beaucoup @quentin pour ton partage, du coup, il faut que je lise tout (j’ai déjà lu ~50% et c’est fascinant!).
Et il me semble que j’ai déjà une première quête, aider à automatiser la traduction de diataxis en fr :wink:

Ensuite, en ce qui concerne mon impliquation, mon intuition est que là où je peux être le plus utile est d’assister les personnes qui veulent documenter/traduire avec mes compétences techniques.
Et à priori, ce ne sera pas avant Juin, ce moment magique où tu sais qu’il n’y a pas grand chose dans le planning et tu penses que tu es libre, mais tu dis cela sur plusieurs choses, et en fait, ce moment s’appelle le déni :wink:
(Et les personnes d’Indie gèrent leur prio comme iels veulent :wink: )

Bonne soiree et bon weekend!

18

Sujet intéressant qui demande effectivement des ressources, du temps et vérification à chaque mise à jour des logiciels

@quentin : merci pour le partage, très intéressant.

Pour la partie outil, j’aime bien MkDocs qui est léger, très simple à utiliser (fichier markdown) et à partager via un repo GIT.

19

Bonjour @reminec

C’est quoi CNFS ?

Nous avons déjà eu des discussions autour de pix sur ce forum https://forum.chatons.org/t/pix-fr-soutient-les-gafam/4180 . Et plus généralement, nous avons eu l’occasion de parler éducation aux médias et éducation à l’occasion du dernier camps chaton.

Pas grave, je sait comment soigner cela. Une bouteille de vin rouge issu des coteaux Belges aop et Hop, des discussions hilarantes.

20

Conseiller National France Service ; pardon pour la digression ça concerne guère la documentation (quoique).
Je me questionnais à éditer mon poste pour enlever ce pâté émotionnel