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.

Etat actuel de la doc

Lors de la préparation de la réunion, on a relevé les points suivants:
  • pages vétustes, redondantes, qui se compliquent à l'extrême à mesure qu'elles sont polluées de conseils spécifiques à une version particulière (entre autres…)
  • Rappel des modèles de pages (templates): application, matériel, portable, tutoriel, portail et dérives liées à chacune
  • design vieillissant et non responsive (ne s'adapte pas automatiquement au petits écrans type téléphone)

Discussion

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

Les difficultés des contributeurs

Ce point concerne plus les gens qui ont déjà contribué au wiki. On a listé les difficultés suivantes d'après nous, au doigt mouillé, mais on aimerait vraiment que les gens qui ont contribué au moins une fois nous donnent leurs impressions en live sur les difficultés qu'ils rencontrent et ce qui les freine dans leurs contributions prise en main de l'éditeur et des balises du wiki
  • Inadéquation des outils pour débattre entre contributeurs (Mailing list, IRC) vis à vis des attentes du public usage des scripts
  • méconnaissance des modèles de page (parfois inadéquats). Usage répété et abusif du sudo et de la ligne de commande
  • Besoin d'un éditeur WYSIWYG? (éditeur dans le genre de libreoffice writer où la mise en forme est visible quand on tape plutôt que de devoir mettre des balises et de prévisualiser)
  • Besoin d'une pop-up type "avez-vous besoin d'aide" comme on en trouve sur certains sites? (ou d'un bandeau résumant la syntaxe et les usages).

Discussion

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

Changement de ligne éditoriale

Il s'agit plus d'un durcissement car l'objectif de la doc a toujours été de présenter du contenu original, francophone, spécifique à Ubuntu, à destination du grand public et des débutants
  • scripts à proscrire (hors tutoriels relatifs au concept de script ?) : ils doivent être hébergés ailleurs que sur le wiki
  • tutoriels très techniques idem:

En effet scripts et tutoriels techniques relèvent plus d'une seule personne experte en son domaine qui est la seule a avoir du recul dessus. Ils ont plus leur place sur le forum ou sur un blog personnel où ils seront en lecture seule, ce qui n'empêche pas de mettre ensuite un lien sur le wiki. Ça implique donc également de bien expliquer comment créer un post sur le forum pour rendre accessible ces scripts, vers quelle partie du forum aller, etc…

  • autres ressources à proscrire: tout ce qui est redondant avec une autre ressource francophone de référence sur le net. Mieux vaut mettre un lien sur un contenu qui sera le plus à jour. De même pour présenter les applications de la logithèque ou certains tutoriels d'aide qui sont en fait déjà présent dans le guide français officiel (aide déjà présente sur le système)
  • les pages obsolètes et/ou ne répondant plus aux critères seront supprimées/archivées/autre?

Discussion

à propos des scripts

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.

à propos du coté un peu généraliste du wiki

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.

à propos des commandes dangereuses

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.

Chantiers prioritaires

  • mise en place du responsive design (adaptation au support: ordinateur, netbook, téléphone, tablette..)
  • mise à jour vers la dernière version de dokuwiki (+php7?). Ou passage à un autre moteur, à étudier, sous réserve d'avoir assez de volontaires. (suggestion de moissan sur le forum, passer à Mediawiki via un script qui fait la conversion depuis dokuwiki)

Discussion

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.

Chantiers importants

On entre dans le domaine où on va avoir besoin de l'aide des contributeurs pour mener les actions parce que clairement juste pour les admins ça va faire too much
  • 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.
  • Étudier la mise en place d'un éditeur WYSIWYG pour simplifier la saisie
  • Régénération automatique de l'archive ZIM permettant de consulter la doc hors ligne. Autres solutions d'export de pages

Discussion

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

Ressources Humaines

  • À l'heure actuelle, 2 administrateurs assez actifs (en fonction des périodes) et une dizaine de contributeurs réguliers
  • Nécessité de l'arrivée de nouvelles personnes pour mettre en place les chantiers: besoin de personnes s'y connaissant en php et html/css, besoin de nouveaux contributeurs, besoin de nouveaux administrateurs.
  • Valoriser et expliquer le rôle des administrateurs pour donner envie de grossir leur rang

Discussion

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

Outils de communication

Les outils de communication actuels ne sont plus en adéquation avec les habitudes des gens. Il y a de moins en moins de contribution sur la mailing list et il n'y a jamais eu personne sur IRC à part les admins les soirs de réunion.
  • L'idée est de passer sur un chat d'équipe plus moderne qu'IRC pour les discussions entre contributeurs: Ont été proposés Télégram (propriétaire), Gitter.im (le chat de github, très utilisé par les communautés open-source mais non totalement libre), et enfin Framateam (libre, open-source, géré par une association française et basé sur Mattermost). Le problème c'est qu'il faut s'inscrire sur un support de plus. Il faut donc bien choisir pour que ce soit pratique, accessible et utilisable depuis un téléphone)
  • Vis à vis de la mailing list et des sujets au long cours qu'il n'est pas forcément opportun de gérer via un chat, l'idée est de créer une partie dédiée à la doc sur le forum Ubuntu afin de gagner en plus en visibilité et d'attirer les utilisateurs des forums

Pour faire simple en ce moment on a une mailing list pour communiquer entre contributeurs et c'est tout. Et plus les années passent plus on se sent seuls dessus

Discussion

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

Non Abordé: Autres propositions

Les points suivants n’ont pas été abordés faute de temps.
  • 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).
  • É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.

Propositions complémentaires au fil de l’eau

  • 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é

Conclusion

Ci après l’ensemble de la liste des choses à faire. L’idéal serait de planifier prochainement une nouvelle réunion pour faire le point, prioriser les tâches, débattre des points non abordés et fixer un calendrier.

Décisions actées

  • 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

Chantiers proposés mais non abordés durant la réunion

  • 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.

Chantiers commencés

Autres suggestions à étudier

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