(j’ai update le message de depart avec le lien vers le code de notre doc, celle ci est maintenant libre)
1 « J'aime »
J’ai animé un atelier dimanche au camp CHATONS pour discuter de la documentation utilisateur.ices. Un constat a été fait que de la très bonne doc’ existait pour la plupart des fonctionnalités et outils de base, mais que souvent les fonctionnalités avancées étaient absentes des documentations. Et que les bonnes doc’ étaient éparpillées sur de nombreux wikis. Le compte-rendu détaillé de l’atelier du camp devrait suivre.
En attendant la proposition d’action qui en est sortie est la suivante :
- Structurer l’état de l’art sur la documentation utilisateur
- Lister les services
- Lister les fonctionnalités de chaque service
- Edition collaborative d’un tableur qui recense les meilleures documentations utilisateur sur les outils/services principaux dans le collectif et leurs fonctionnalités
- Vote pour déterminer les outils et fonctionnalités sur lesquels prioriser un travail collaboratif de rédaction de doc’
Durant la deuxième heure de l’atelier, on a commencé à travailler et on appelle donc à continuer ce travail collaborativement en ligne. Vous pouvez participer à la rédaction de ce tableur collaboratif :
- En ajoutant des liens vers de bons tutoriels (colonnes) de découverte de l’utilisation d’un outil que vous connaissez
- En ajoutant détaillant un service et ses fonctionnalités (ligne). En particulier une fonctionnalité pour laquelle vous ne connaissez pas de doc’
Une réunion aura lieu pour travailler sur le document et définir la procédure pour la phase de vote à la rentrée après la prochaine réunion sur la formation. Il faudra qu’on décide si un ou deux groupes de travail sont nécessaires pour traiter les thématiques documentation utilisateur et formation « un peu technique » des bénévoles. En tous cas il faudra sans doute un « gros tuyau » (une forte collaboration) entre ces deux travaux.
3 « J'aime »
Bonjour,
Je n’aurai pas beaucoup de temps pour les mois à venir pour participer aux ateliers sur la documentation, donc je me permets d’apporter des éléments de réflexion supplémentaires sur ce sujet en présentant notre documentation ici (si ça peut aider) :
https://docs.lacontrevoie.fr/
Structure
Elle est divisée en quatre sections :
- Activités de sensibilisation : on tient un registre de nos activités, et on documente nos confs, nos ateliers et la tenue de nos stands ;
- Technique : toute la documentation technique, de notre infra en général, de nos services et de leurs dépendances (stockage, monitoring, backups, protocoles spécifiques…), les routines (cron), les scripts un peu personnalisés / faits maison et les guides de maintenance ;
- Administratif [WIP] : comment on réalise notre compta, comment on demande nos agréments / subventions, comment on rédige des réponses à nos emails, comment on rédige notre rapport moral / financier, nos procès verbaux, comment on prend des décisions collectives…
- Communication [WIP] : des informations sur nos outils de communication physiques (matériel de stand, tee-shirts…) et numériques (matrix, réseaux sociaux).
Nous n’avons pas de documentation utilisateur·ice au-delà des pages de présentation de nos services.
L’objectif de cette documentation est tantôt de servir de guide pas-à-pas, tantôt de référence pour nos membres bénévoles ou pour des personnes extérieures qui souhaiteraient se renseigner sur nos pratiques internes, selon les sections. Les objectifs de chaque section sont explicités sur la page d’accueil de la section.
Niveau backend
C’est un site statique (Zola), le code est là. Pour l’édition, on intègre un bouton « éditer cette page » sur chaque page de la doc qui redirige vers la page d’édition de notre instance Gitea.
On n’a rien inventé : on fait tout pareil que Framasoft (pour leur doc technique et de participation, notamment) sauf qu’iels utilisent GitLab à la place, grâce au logiciel HonKit basé sur Gitbook.
L’édition n’est pas aussi intuitive que sur Bookstack ou Dokuwiki, mais reste quand même globalement accessible pour des personnes non-initiées :
- Gitea intègre un éditeur qui rend la modification du markdown plutôt facile ;
- Zola intègre un système de macros/shortcodes pour insérer des bouts de HTML sans avoir à en écrire (exemple :
{% message("todo") %}pour afficher un bloc formaté indiquant qu’une page est en construction) ; - pas besoin de ligne de commande : une fois la page éditée dans l’interface web, la PR est automatiquement créée lors de la mise à jour de la page.
On a choisi cette solution pour sa légèreté : on s’évite un moteur de rendu + une base de données, et toutes les pages sont dans un dépôt au format markdown.
3 « J'aime »
Salut à tous,
je ne me risquerais pas à promettre une forte participation, par contre, en raison d’une malédiction qui me suit depuis de très nombreuses années, je vois immédiatement une très grande part des erreurs typographiques, orthographe et accords de grammaire.
Je propose donc une contribution de relecteur/correcteur de ces aspects, et ainsi alléger la tâche de celles et ceux qui ont la malédiction inverse! 
2 « J'aime »
Hello, je souffre de la même malédiction, je peux donc contribuer de la même façon si besoin
3 « J'aime »