ZEP-16 : Page de proposition de corrections

Cette ZEP, au delà du scope décrit ci-dessous a surtout pour but, de poser les bases d'un socle technique, flexible et évolutif pour de nombreux cas d'usages à venir.

État des lieux et problématique

Aujourd'hui ZdS héberge du contenu, rédigé par des membres. La publication du contenu suit le workflow suivant :

Cependant, certaines publication on très souvent des fautes, et la seule méthode existante pour pouvoir proposer des correctifs sur le contenu, est d'aller dans la zone réservée aux commentaire (si le contenu est déjà publié) ou d'aller dans le topic dédié (si le tutoriel est en beta) et ceci pose plusieurs problèmes :

• Il faut copier nous même les bouts de texte incriminé, scroller, jusque dans la zone des commentaires (pour un contenu publié) et coller le texte faux et la correction en dessous. On perd donc rapidement le fil de la lecture et ça ralenti le processus
• Les commentaires de types "corrections" rajoutent du bruit dans les commentaires de la publication (car ceux-ci devrait être invalidé après correction).
• Tout un tas d'autres raisons que j'oublie

Ces problèmes diminuent le nombre de participation à des corrections collectives, car au bout de 2-3 fautes, on a plus le courage de continuer en scroller dans tous les sens.

La solution

Coté fonctionnel

Ce que je propose est simple. En plus de ce qui existe aujourd'hui, il faudrait :

1. Rajouter dans la colonne de gauche un bouton intitulé "Mode correctif" (ou autre nom parlant)
2. En cliquant sur ce dernier, on devrait tomber sur une page qui ressemble exactement à la page qu'on avait avant, le seul élément visuel en plus serait, lorsqu'on passe la souris sur un élément (paragraphe, image, titre ou liste à puce) du contenu, l'élément se mets en surbrillance.
3. En cliquant sur l’élément, nous avons une modale qui s'affiche par dessus, avec par défaut avec le texte de l'élément sur lequel on a cliqué, et en dessous un zone de texte avec ce même contenu, mais au format markdown (prêt pour la modif). Ainsi qu'un bouton pour envoyer les modifications.
4. Une fois les modifications envoyées, l'auteur reçoit dans la zone de notification une alerte qui représente chaque commentaire d'une de ses publications.
5. Tout ceux qui consultent la publication en "Mode correctif" peuvent voir (juste après le paragraphe incriminé) la(les) proposition(s) de correction(s).
6. Si c'est possible techniquement, on pourrait rajouter un bouton "Accepter la proposition" disponible uniquement pour l'(s) auteur(s), qui permettrait de remplacer automatiquement le texte incriminé par le bon.

L'implémentation technique

Ce n'est pas une mince affaire coté technique, car il faut jouer avec les modules zmarkdown, tutoriels/articles et front-end. Ce que je vais décrire ci-dessous n'est qu'une proposition, elle peut toujours être modifiée.

Coté zmarkdown

Actuellement on dispose d'un filtre emarkdown qui renvoit du html pour le contenu qui ressemble à ça :

1
2
3
4
5
6
7
8

<p>Je ne sais pas vous, mais moi, j'adore Zeste de Savoir. Pourtant, je trouve qu'il manque un petit quelque chose à notre mascotte, Clem : <strong>une histoire</strong> !</p>
<h3>Chapitre 1 : Prologue</h3>
<p>Il faisait noir.</p>
<h3>Et la suite ?</h3>
<ul>
<li><a href="http://endlesszeste.tk/">Le livre des aventures</a></li>
</ul>
<p>À vous de jouer ! <img alt=":D" src="/static/smileys/heureux.png"></p>

L'idée serait d'avoir un autre filtre emarkdown_interactive qui renverrait quelque chose qui ressemble à ça:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

<p>Je ne sais pas vous, mais moi, j'adore Zeste de Savoir. Pourtant, je trouve qu'il manque un petit quelque chose à notre mascotte, Clem : <strong>une histoire</strong> !</p>
<a href="#hash-01" class="ico-after open-modal">Corriger</a>
<form id="hash-01" class="modal modal-large" action="">
<p>Je ne sais pas vous, mais moi, j'adore Zeste de Savoir. Pourtant, je trouve qu'il manque un petit quelque chose à notre mascotte, Clem : <strong>une histoire</strong> !</p>
<hr />
<textarea class="md-editor">Je ne sais pas vous, mais moi, j'adore Zeste de Savoir. Pourtant, je trouve qu'il manque un petit quelque chose à notre mascotte, Clem : **une histoire** !</textarea>
<button type="submit" name="add_comment">Confirmer</button>
</form>
<h3>Chapitre 1 : Prologue</h3>
<a href="#hash-02" class="ico-after open-modal">Corriger</a>
<form id="hash-02" class="modal modal-large" action="">
<p><h3>Chapitre 1 : Prologue</h3></p>
<hr />
<textarea class="md-editor"># Chapitre 1 : Prologue</textarea>
<button type="submit" name="add_comment">Confirmer</button>
</form>
<p>Il faisait noir.</p>
<a href="#hash-03" class="ico-after open-modal">Corriger</a>
<form id="hash-03" class="modal modal-large" action="">
<p>Il faisait noir.</p>
<hr />
<textarea class="md-editor">Il faisait noir.</textarea>
<button type="submit" name="add_comment">Confirmer</button>
</form>
<h3>Et la suite ?</h3>
<a href="#hash-04" class="ico-after open-modal">Corriger</a>
<form id="hash-04" class="modal modal-large" action="">
<p><h3>Et la suite ?</h3></p>
<hr />
<textarea class="md-editor">## Et la suite ?</textarea>
<button type="submit" name="add_comment">Confirmer</button>
</form>
<ul>
<li><a href="http://endlesszeste.tk/">Le livre des aventures</a></li>
<a href="#hash-05" class="ico-after open-modal">Corriger</a>
<form id="hash-05" class="modal modal-large" action="">
<p><li><a href="http://endlesszeste.tk/">Le livre des aventures</a></li></p>
<hr />
<textarea class="md-editor">- [Le livre des aventures](http://endlesszeste.tk/)</textarea>
<button type="submit" name="add_comment">Confirmer</button>
</form>
</ul>
<p>À vous de jouer ! <img alt=":D" src="/static/smileys/heureux.png"></p>
<a href="#hash-06" class="ico-after open-modal">Corriger</a>
<form id="hash-06" class="modal modal-large" action="">
<p>À vous de jouer ! <img alt=":D" src="/static/smileys/heureux.png"></p>
<hr />
<textarea class="md-editor">À vous de jouer ! ![:D](/static/smileys/heureux.png)</textarea>
<button type="submit" name="add_comment">Confirmer</button>
</form>

Pour l'identifiant de chaque formulaire, je pense qu'on peut utiliser un hash de type bijectif du bout de texte pour s'assurer qu'on ait un seul identifiant par formulaire et que zmarkdown peut le construire dans son coin. Bon, j'ai fais ça à la main, mais c'est pour donner une idée. Et la page de correction sera donc disponible pour être manipulée par du JS.

Du coté du Javascript

Le boulot ici ne devrait pas être compliqué. La seule chose à faire consiste à afficher le bouton "corriger" (qui sera par défaut à display=none) au survol du texte. Le JS devra repérer les button ayant la classe open-modal. Pour le reste ça sera au back-end d'assurer l'enregistrement des commentaires.

PS : Nul besoin de l'Ajax pour le moment, ça arrivera dans un second temps (une fois cette base fonctionnelle et stabilisée).

Du coté des modules django.

Il faudrait une table avec les colonnes :

• extract
• hash
• text
• text_html

Une view sera chargée de rajouter dans la table chaque nouveaux commentaires. Cette table servirait aussi pour afficher chaque commentaire d'une publication.

Voila, normalement sauf mauvaise surprise, cette ZEP devrait être sympa a implémenter.

Je préviens, actuellement dans le zmarkdown il n'y a rien d'adapté à conserver le liens source <-> html de sortie. Tant qu'on reste au niveau bloc, comme tu le propose, ça devrait rester faisable mais ça va demander pas mal d'instrumentation et de modifs du code. D'autant que là j'oublie les morceaux qui sont fait à coup de pré-processeurs.

Sachant que le module est voué a disparaître à moyen terme, ça me parait compliqué.

ça devrait rester faisable mais ça va demander pas mal d'instrumentation et de modifs du code

Tu pourrais développer cette partie ? J'avoue avoir du mal à mesurer l'ampleur de la tâche ici.

Actuellement, la transformation du texte brut en html se fait ainsi dans Python-Markdown, en gros :

1
2
3

Source ---> Source' ---> AST (arbre dom/xml) ---> AST' ---> HTML
        ^            ^                        ^         ^
     Préprocs.     Proc-blocs            tree-procs  Serialisation

Les différentes étapes sont en faite des séries de transformations, incluse ou sous forme d'extensions (mais en gros ce sont les mêmes).

La première étape fait passer des pré-processeurs. Déjà ça pose des problèmes car ça revient à transformer un fichier source en un autre (+mémorisation de quelques infos). Là ça pose déjà des problèmes car je vois mal comment on peut garder les liens (avec des placeholder tout moches ?).

Ensuite on fait passer les processeurs de blocs. C'est là qu'intervient la découpe en paragraphe, en liste, les blocs de codes, d'infos, etc. C'est en gros les unités que tu veux extraire. C'est donc ici qu'il faut réussir a mémoriser le lien code source <-> AST.

Le gros du problème provient des transformation de blocs. Il faut toutes les modifier pour qu'elles enregistres le bloc markdown qu'elles traitent en lien avec les éléments de l'AST qu'elles produisent.

Il faudrat ensuite dans les dernieres transformations de l'arbre que cette liaison est propagé. Par exemple la balise transforme au niveau de l'arbre l'information sémantique d'une balise vidéo en le bloc html correspondant au provider. Il faut donc modifier aussi ces modules pour propager les liens.

Enfin il faut je pense à la fin intercaler un dernier processeur de l'arbre pour qu'il insere directement dans l'arbre ces infos et re-insére les parties virés/transformé par les pré-processeurs qui vont etre transformés en html.

Cette ZEP, au delà du scope décrit ci-dessous a surtout pour but, de poser les bases d'un socle technique, flexible et évolutif pour de nombreux cas d'usages à venir.

Il me semble que la ZEP-27 est censée se charger de cela.

En cliquant sur l’élément, nous avons une modale qui s'affiche par dessus, avec par défaut avec le texte de l'élément sur lequel on a cliqué, et en dessous un zone de texte avec ce même contenu, mais au format markdown (prêt pour la modif). Ainsi qu'un bouton pour envoyer les modifications.

Il faut selon moi deux champs facultatifs, mais dont au moins un doit être rempli : un pour faire la remarque, i.e. expliquer ce qui ne va pas, et un second pour proposer une correction.

Si c'est possible techniquement, on pourrait rajouter un bouton "Accepter la proposition" disponible uniquement pour l'(s) auteur(s), qui permettrait de remplacer automatiquement le texte incriminé par le bon.

Cela me semble nécessaire, et pas uniquement pour l'auteur. Il est très appréciable, pour le relecteur, de savoir quelles remarques ont été prises en compte ou non, afin d'éviter de les rabâcher (et, potentiellement, de demander à l'auteur ce qui ne lui convenait pas avec les autres).

En fait, ce qui serait à implémenter ici est peu ou prou le principe des line notes de GitHub. Il serait pratique de pouvoir réagir à une proposition de correction, ne serait-ce que pour corriger cette proposition.

Dans un premier temps, et peut-être à long terme aussi, on pourra se contenter de faire des PR (ZEP-08, on te veut) avec des balises de commentaire :

1
2
3
4
5

<--COMMENT

Ce texte n'apparaît pas dans le rendu HTML.

COMMENT-->

L'objectif ici serait alors juste de faire une interface pour commenter facilement, réagir à des commentaires, en supprimer, etc.

D'autant plus qu'on peut insérer un commentaire en plein milieu du texte sans perturber la mise en page. En effet :

1
2
3
4
5

D'autant plus qu'on peut insérer un commentaire en plein<--COMMENT

Pouet pouet

COMMENT--> milieu du texte sans perturber la mise en page. En effet :

Sans aller jusqu'à identifier les éléments d'une section, ni parler de pull requests, ne pourrait-on pas étendre la fonctionnalité "Signaler une faute", en permettant au lecteur d'éditer directement le texte ? On aurait un bouton pour en quelque sorte citer la section (comme on cite des messages sur le forum). Au clic sur ce bouton, la section se transformerait en textarea contenant le texte sous forme citation (comme sur le forum). On aurait alors plus qu'à commenter un passage, comme on le fait déjà en bêta. L'avantage est qu'on n'a pas à ouvrir d'autre onglet et qu'on peut immédiatement cibler la section concernée, de la même manière qu'un signalement de faute via le bouton intègre au MP le chapitre visé.

En fait, l'idée est vraiment de pouvoir commenter le tutoriel en place.

J'ai bidouillé un truc : https://jsfiddle.net/4zxLypbo/1/embedded/result/. Au clic sur le bouton "Mode correction", la division contenant le texte est changée en sa jumelle éditable (contenteditable="true").

L'idée serait d'avoir le bouton "Mode correction" pour chaque section. On ajouterait un bouton pour envoyer les corrections par MP ou dans le sujet de bêta, et pourrait utiliser le local storage pour sauvegarder ses corrections jusqu'à l'envoi.

Ce n'est bien sûr qu'une ébauche. Notamment, on effectue ici les corrections sur le code HTML, mais peut-être serait-il préférable de le faire sur le Markdown, notamment pour voir le contenu mathématique, ajouté dynamiquement en JS.

Merci.

Vayel, merci pour tes investigations.

L'idée est à la fois de faciliter les annotations/corrections d'un lecteur, mais aussi de faciliter l'intégration de ladite correction par l'auteur. La façon dont tu vois le problème me semble bien du point de vue lecteur, mais du point de vue auteur ça reste assez compliquer de traiter tous les MPs à la main.

Il faudrait de mon point de vue, une branche "correction-<id>" cotée serveur sur laquelle on enregistre les corrections. Le correcteur devrait pouvoir éditer chaque ligne, une par une, et chaque ligne éditée serait un commit. Ce qui permettra à l'auteur de décider d'intégrer le(s) commit(s) qui l’intéresse(nt) via un git cherrypick effectué coté serveur.

L'affichage du mode correction ne sera qu'une sorte d'affichage d'un diff entre la branche principale et la(les) branche(s) de corrections.

Une fois que l'auteur a fini de choisir les corrections qu'il jugent intéressante, il peut déclarer la branche "correction-<id>" comme traitée, ce qui supprimera la branche de correction coté serveur.

Cette manière de faire les choses ne permet pas de "commenter un texte", mais uniquement de proposer des corrections. Mais elle a le mérite d'être plus rapidement implémentable pour une version 1 de la zep.

Le problème de ce que tu proposes, c'est que ça se base sur git, et que la ZEP-08 ne sera pas implémentée avant longtemps (même si on s'y mettait aujourd'hui). Il me semble donc préférable dans un premier temps de se contenter d'améliorer uniquement la fonctionnalité "Signaler une faute", qui est quasiment inutilisable à l'heure actuelle.

Le problème de ce que tu proposes, c'est que ça se base sur git, et que la ZEP-08 ne sera pas implémentée avant longtemps (même si on s'y mettait aujourd'hui)

En effet ça se base sur git, mais n'a pas la même ambition que celle de la ZEP-08. Créer une branche, la supprimer, faire une comparaison entre deux branches, on sait déjà le faire avec la bibliothèque git utilisée aujourd'hui. La ZEP-08, elle voudrait faire des pull request et proposer de quoi gérer les conflits quand il y'en a. Avec le système que je propose on s'épargne la gestion des conflits et on ne propose pas de PR au sens git du terme.

Comment ça se passe quand la version brouillon diffère de celle publiée ? Par exemple, un correcteur propose une correction C, que l'auteur applique, puis un autre correcteur propose la même correction C, la version publiée n'ayant pas encore mise à jour.

Dans le cas que tu décris, si un deuxième correcteur propose la même correction C, la première étant déjà appliqué, le diff entre les deux versions sera nul, et donc l'auteur ne verra jamais la deuxième demande. Le diff doit se faire par rapport au brouillon pour éviter de surcharger l'auteur avec de l'information redondante.

Je comprends mieux, merci. Par contre, j'imagine que la question reste de définir ce qu'est une ligne :

Le correcteur devrait pouvoir éditer chaque ligne, une par une, et chaque ligne éditée serait un commit.

En outre, au moment de l'édition, le correcteur aurait accès uniquement au code Markdown de ladite ligne, ou tout le textarea du chapitre/de la section ?

Autant il me semble assez simple de distinguer les éléments dans le HTML (il suffit de donner des identifiants aux conteneurs), autant j'ai plus de mal à voir comment faire la correspondance avec le Markdown.

En outre, au moment de l'édition, le correcteur aurait accès uniquement au code Markdown de ladite ligne, ou tout le textarea du chapitre/de la section ?

Uniquement à une ligne sinon ont perd l'intéret

Autant il me semble assez simple de distinguer les éléments dans le HTML (il suffit de donner des identifiants aux conteneurs), autant j'ai plus de mal à voir comment faire la correspondance avec le Markdown.

C'est pourquoi, il y'aurait un peu de taff coté lib markdown pour pouvoir rajouter un mode qui parse le markdown pour le transformer en html + markdown afin de manipuler plus facilement coté front la page.