Compte rendu de la réunion du 26 juin 2017

La réunion avait pour but de faire le point sur l'état actuel de la documentation, identifier ce qu'il faut changer, et se fixer des objectifs raisonnables en fonction de la taille de l'équipe afin d'avoir une documentation aussi à jour et aboutie que possible à l'horizon avril 2018. En effet la première LTS depuis l'abandon d'Unity sortira à cette époque.

Une réunion préliminaire entre administrateurs de la documentation a eu lieu le 31 mai pour préparer celle ci. Le compte rendu est disponible ici.

Pour la suite de ce document, seront d'abord rappelés ce qui était écrit à l’ordre du jour, suivit par ce qui a été dit lors de la réunion.

Le responsive design n’est pas un obstacle majeur, c’est plus une question de thème, ça sera réglé lors de la mise à jour de dokuwiki

Précision sur les pages redondantes: dans de rares cas plusieurs pages existent pour traiter le même sujet. Plus fréquemment, les contributeurs ont tendance à réinventer la roue en expliquant des choses qui sont déjà expliquées ailleurs, typiquement comment installer un paquet. Enfin il y a des redondances lorsque la doc aborde des sujets qui sont déjà abordés dans d’autres ressources francophones plus spécialisés sur la question abordée

Apparemment certaines pages sont trop longues, un peu fouilli, le wiki manque de structure. De plus en l’état actuel des choses il devient plus critique de mettre à jour les pages existantes que d’en ajouter de nouvelles.

Il y a un problème avec les pages dédiées à l’installation: du fait du grand nombre de possibilités en matière de variantes et de types d’installations, le débutant est facilement perdu, il faudrait repenser la démarche pour rendre le tutoriel de base plus directif (note: voir si le guide officiel ne fait pas précisément ça).

On tombe d’accord pour arrêter (sauf exception justifiée) de mettre les tag des versions intermédiaires sur les pages, pour se concentrer uniquement sur les LTS

Concernant le WYSIWYG, plusieurs solutions existent mais l’idéal serait d’en trouver une qui s'intègre à Dokuwiki sous la forme d’un plugin et qui génère du code dokuwiki, de manière à ce que les contributeurs qui le souhaitent puissent basculer en mode avancé et modifier directement le fichier source en suivant la syntaxe dokuwiki

Une difficulté remontée est que les conseils donnés aux contributeurs sont trop directifs, qu’on les noie sous une avalanche de règles à suivre, ce qui ne les encourage pas à contribuer

Les contributeurs ne comprennent pas forcément en quoi consiste un mini-tutoriel, y compris certains participants de la réunion, qui n’ont pas le réflexe d’aller voir de quoi il s’agit, et qui après coup ont remonté que oui, mais les mini-tutoriels ne sont pas si petits que ça et qu’il n’est pas possible d’y trouver l’info recherchée rapidement

Le sujet des contraintes de rédaction semble celui qui revient le plus. Il est suggéré que des contributeurs pourraient se charger de mettre en forme après coup. En fait c’est déjà un peu le cas, mais c’est une tache ingrate et peu valorisante, autant bien faire tout de suite. On décide qu’un effort sera apporté sur les conseils aux contributeurs

L’idée de contributeurs experts chargés de coacher les autres et de valider la mise en forme est proposée

La plupart des gens ont du mal à comprendre pourquoi il faudrait bannir les scripts et les tutoriels techniques alors que c’est une partie importante du wiki. Explication: En fait le problème des articles pointus c'est qu'il n'y a quasiment que la personne qui a écrit la page qui a suffisamment de recul dessus pour la mettre à jour. Alors que le principe d'un wiki c'est que tout le monde collabore. Et au bout de quelques années quand il faut mettre à jour la page les contributeurs présents ne savent pas trop quoi en faire. Il faudrait trouver une solution pour que la personne qui crée un article très technique ou un script assez long soit la seule à pouvoir l'éditer/mettre à jour, et du coup c'est pour ça que en dehors du wiki parait mieux, mais pas forcément super loin non plus, ça peut etre sur une page perso, ou sur le forum, ou on peut mettre à dispo un blog collaboratif ou autre… Quelqu’un demande ce qu’on entend par tutoriel technique ⇒ On parle des articles très techniques type compiler son noyau, utiliser un éditeur hexadécimal pour analyser le début de son disque dur, capturer des trames réseau, etc. Un tutoriel pour installer une imprimante wifi est technique, mais garde sa place dans la doc. La limite se situe vraiment à partir du moment où il devient peu vraisemblable que quelqu’un d’autre que le créateur du tutoriel sache le maintenir dans le temps.

La question des scripts revient. La raison pour laquelle ça pose problème ainsi que la problématique de sécurité liée au fait que finalement sur un wiki n’importe qui peut modifier le script et introduire du code pernicieux est comprise de tous, mais il est suggéré que les scripts soient relus par les modérateurs et verouillés. Réponse: contradictoire avec le principe d’un wiki, impossible à mettre en place en pratique, et tres contraignant pour les modérateurs. On s’accorde que le plus simple pour allier sécurité et facilité de contribution, c’est que le contributeur qui souhaite ajouter un script dans une page créée un post sur le forum au sujet de son script dans la section “Trucs, astuces et scripts utiles”, et que dans sa page, il indique simplement l’adresse de son sujet, ce qui permettra de plus aux gens qui le souhaitent, de poser des questions sur le script, ou de suggérer des améliorations et d’en discuter. C’est également plus logique comme ça car la majorité des contributeurs ne sont pas experts en scripts alors qu’il y a des pointures sur le forum.. Il est également proposé d’afficher un avertissement à ce sujet lorsque quelqu’un tente d’insérer les balises script dans une page. Ou encore de proposer un cartouche uniformisé pour présenter les scripts sur le forum

Question sur ce qu’on entend par script ⇒ dés qu’il y a au moins deux lignes de commandes.

Autre question, actuellement le wiki ne parle pas que d’Ubuntu et a un coté wiki généraliste que certains voudraient conserver. Malheureusement, eût égard à la taille restreinte de l’équipe de contributeurs réguliers c’est un luxe difficile à s’offrir. Après si tous ceux qui militent pour conserver cet aspect là intègrent l’équipe et se chargent de maintenir ces pages pourquoi pas.. Mais plus on va s’éloigner du coeur du sujet, plus les pages vont être spécifiques à des sujets que seul le contributeur qui les a créé maîtrise. On retrouve les difficultés liées aux tutoriels très techniques.

Question sur les lignes de commande dangereuses: les gens ne comprennent pas bien pourquoi il faudrait bannir le sudo de la doc. ⇒ En fait le sudo est utilisé à tort et à travers. Par exemple pour passer en mode administrateur sur le terminal, on trouve indifféremment du “sudo -s” ou du “sudo -i” et la plupart des gens n’ont pas la moindre idée de la différence entre les deux. Ou encore on trouve régulièrement des gens qui utilisent sudo pour lancer un logiciel graphique, alors qu’en théorie il faudrait utiliser l’utilitaire approprié à l’environnement graphique (gksudo pour gnome). Enfin, les lignes de commandes en sudo sont généralement données sans la moindre explication de ce que ça implique et pourquoi il faut taper son mot de passe, et pour ajouter à la confusion, les dernières versions d’Ubuntu affiche un gros avertissement bien dissuasif lorsqu’on copie-colle une ligne de commande en sudo dans le terminal.

Il est à noter qu’il existe un tutoriel sur le sudo mais pas de mini tutoriel. On convient de créer un mini-tutoriel dédié au sudo, de le faire pointer sur la page de la doc dédiée au sudo, et que désormais on évitera de donner le sudo dans la doc et qu’on dira plutôt “avec les droits d’administrateur, blabla”, le lien renvoyant vers le mini-tutoriel. En effet les gens qui comprennent ce que ça implique sauront qu'ils doivent mettre un sudo et les autre il vaut mieux qu'ils s'abstiennent jusqu’à ce qu’ils aient lu les explications idoines.

Tout le monde est d’accord pour dire qu’on laisse tomber l’idée de passer à Mediawiki. On prend acte qu’on va migrer vers la dernière version de dokuwiki, laquelle ne nécessite pas php7 (migration abandonnée également). Le responsive design viendra avec le thème choisi post migration. Tout le monde est d’accord on passe vite dessus.

NB: il y aura probablement des ajustements à faire de la charte graphique.

Pas de réaction particulière. Les gens sont plus intéressés par qui fait quoi. On passe au point suivant.

On est revenu en fin de réunion sur l’idée du meta-moteur. Une solution basée sur Elasticsearch aurait été envisagée pour indexer l’ensemble des ressources

Petite précision sur la logithèque: il est envisagé de regarder si les descriptions qu’elle contient ne peuvent pas être récupérées et indexées pour servir de base et éviter de réinventer la roue dans les pages sur les applications

Il est fait mention que pour les parisiens, il possible de se réunir les jeudis soirs (certains membres de l’association se réunissent déjà toutes les semaines les jeudis), pour contribuer sur n'importe quel sujet, du contenu, de la technique ou autre

Parmi les personnes présentes, il y a aussi bien des gens qui accepteraient d’aider vis à vis de l’administration des serveurs ou pour tester le passage à un dokuwiki récent, ou pour apprendre à contribuer. Tout le monde est le bienvenu de toute manière

Un système de parrainage est suggéré pour que des contributeurs chevronnés encadrent les nouveaux.

D’un point de vue général les gens ne comprennent pas bien ce que fait un admin. Une clarification semble s’imposer

L’introduction d’un rang intermédiaire de modérateur est suggéré pour les contributeurs chevronnés qui veulent bien aider à encadrer le wiki mais sans avoir des responsabilités d’admin

Un sondage parmi les contributeurs présent montre une nette préférence pour continuer d’utiliser la mailing list en complément de Mattermost. Le forum est plutôt vu comme une porte d’entrée. Il va peut être s’avérer opportun d’y placer un sujet épinglé sur comment participer à la doc. Personne n’est favorable à la solution IRC

Il semblerait qu’un Mattermost maison soit à l’étude par l’association, auquel cas on pourrait y migrer le moment venu

On pourrait refaire des réunions régulièrement pour faire le point, sur une base à définir (bimensuelle, mensuelle?), mais sinon le salon est ouvert en permanence, tout le monde peut venir y parler

• Ce serait bien de pouvoir filtrer la doc en fonction d'une version Ubuntu pour ne pas voir ce qui est spécifique aux autres versions, mais ça peut être à double tranchant, car si les pages ne sont pas à jour, on n’accédera pas aux pages des anciennes versions? et de plus il faut que les Tags de version soient renseignés. À moins que lors d'une création/modifications un certains nombre de choses à cocher soient obligatoires pour pouvoir valider un enregistrement. Pour aller plus loin on pourrait mettre des avertissements lors de la soumission d'une page lorsqu'il est possible de contrôler automatiquement qu'il y a potentiellement un problème : « Vous n'avez pas mis de tag à cette page » « Il manque la partie pré-requis sur cette page applications… » Ça ferait gagner un certains temps lors des relectures de certaines pages. Avec le développement rapide des technologies Snappy et Flatpak, ce genre de limitation pourrait devenir caduque d'ici peu de temps.

• Ce serait bien de pouvoir ajouter quelques scripts qui s’exécutent automatiquement régulièrement pour faire des corrections basiques, du genre mettre les espaces insécables entre la ponctuation qui le nécessite. Nettoyer la rubrique image de toutes les images obsolètes (non liées à une page). Lors de l'export en ZIM ça avait pu être fait (pour les images).

• Réparer ce truc mystérieux : https://doc.ubuntu-fr.org/wiki/orphelines (ATTENTION à ouvrir dans un navigateur en mode terminal sinon ça crashe tout)

• Ceci https://tour.ubuntu-fr.org/fr/index.html me renvoie une erreur, et devrait à long terme être substitué par un équivalent "gnome shell"

• Évaluer la possibilité de figer la documentation à chaque version dans une branche garage gelée (à la facon svn). Ainsi les pages ou remarques obsolètes peuvent être supprimées sans scrupules dans les pages de la nouvelle version.

Le wiki aurait pour architecture :

              / la version en cours ECRITURE
              /16-10/ LECTURE SEULE
              /16-04/ LECTURE SEULE
              /LTS/ ECRITURE si nécessaire de modifier...
              etc.

• Cartouche en haut des pages de la doc pour inciter les lecteurs à participer.
• Il y a une discussion sur le moteur de recherche de la doc, actuellement google, qui est difficile à remplacer par une solution libre, mais qui pourrait être encapsulé dans le méta-moteur envisagé

• On tombe d’accord pour arrêter (sauf exception justifiée) de mettre les tag des versions intermédiaires sur les pages, pour se concentrer uniquement sur les LTS
• Le sujet des contraintes de rédaction semble celui qui revient le plus. Il est suggéré que des contributeurs pourraient se charger de mettre en forme après coup. En fait c’est déjà un peu le cas, mais c’est une tâche ingrate et peu valorisante, autant bien faire tout de suite. On décide qu’un effort sera apporté sur les conseils aux contributeurs
• L’idée de contributeurs experts chargés de coacher les autres et de valider la mise en forme est proposée
• On s’accorde que le plus simple pour allier sécurité et facilité de contribution, c’est que le contributeur qui souhaite ajouter un script dans une page créée un post sur le forum au sujet de son script dans la section “Trucs, astuces et scripts utiles”, et que dans sa page, il indique simplement l’adresse de son sujet. .. Il est également proposé d’afficher un avertissement à ce sujet lorsque quelqu’un tente d’insérer les balises script dans une page. Ou encore de proposer un cartouche uniformisé pour présenter les scripts sur le forum
• Il est à noter qu’il existe un tutoriel sur le sudo mais pas de mini tutoriel. On convient de créer un mini-tutoriel dédié au sudo, de le faire pointer sur la page de la doc dédiée au sudo, et que désormais on évitera de donner le sudo dans la doc et qu’on dira plutôt “avec les droits d’administrateur, blabla”, le lien renvoyant vers le mini-tutoriel.
• mise à jour de dokuwiki, pas de migration à mediawiki

• Lister l'ensemble des ressources francophones autour d'Ubuntu qui sont externes à la documentation.
• Étudier la mise en place d'un meta-moteur de recherche permettant de rechercher à travers tous ces supports.
• Régénération automatique de l'archive ZIM permettant de consulter la doc hors ligne. Autres solutions d'export de pages
• Ce serait bien de pouvoir filtrer la doc en fonction d'une version Ubuntu
• Ce serait bien de pouvoir ajouter quelques scripts qui s’exécutent automatiquement régulièrement pour faire des corrections basiques, du genre mettre les espaces insécables entre la ponctuation qui le nécessite. Nettoyer la rubrique image de toutes les images obsolètes (non liées à une page). Lors de l'export en ZIM ça avait pu être fait (pour les images).
• Réparer le plugin qui affiche les pages orphelines (qui fait crasher le navigateur)
• Le certificat de sécurité de https://tour.ubuntu-fr.org/fr/index.html est expiré depuis le 20 mai. Il faudrait le renouveler et envisager de le mettre à jour vers une version récente d’ubuntu (au lieu de la 14.04 actuellement)
• Évaluer la possibilité de figer la documentation à chaque version dans une branche garage gelée (à la façon svn). Ainsi les pages ou remarques obsolètes peuvent être supprimées sans scrupules dans les pages de la nouvelle version.

• Mise à jour de dokuwiki et test des nouveaux plugins
• Liste des ressources francophones: https://annuel2.framapad.org/p/liste_ressources_francophones_linux
• Ajout de modérateurs pour aider les admins
• Meilleure présentation du rôle d’admin

• Cartouche en haut des pages de la doc pour inciter les lecteurs à participer.
• Système de parrainage
• Réunion IRL