Tutoriels et articles : les nouveautés de la version 12 !

• La ligne éditoriale officielle de Zeste de Savoir
• Les injections SQL

Après une version 15.7 Gaston (non Gaston n'est pas un agrume, c'est juste qu'il est en retard) qui venait stabiliser le site, nous repartons vers les cieux de l'ajout de fonctionnalités (et lesquelles !) avec la version 12, Cordelia, publiée le 29 octobre 2015.

Nous sommes bien loin de battre le record des tickets GitHub fermés, détenu par la version Cédrat (15.6) avec ses 120 tickets ; en revanche, cette version contient l'aboutissement de neuf mois de travail, de décembre 2014 jusqu'à août 2015, mené essentiellement par deux contributeurs actifs : artragis et pierre_24.

Ces derniers se sont adonnés à la refactorisation du module rédactionnel, ce même module qui s'occupe de la gestion des tutoriels et articles, de la création à la publication, en passant par la bêta, l'import ou encore la validation. Mais pas seulement refactorisé : également corrigé, puis testé en profondeur. Tout ce travail a été réalisé dans le cadre d'une ZEP, la douzième du nom.

Si vous le voulez bien, partons sans plus attendre à la rencontre de cette nouvelle version.

• C'est l'histoire de la vie...
• Que s'est-il passé ?
• Vers l'infini et au delà !

C'est l'histoire de la vie...

Sur notre petit îlot de partage libre de connaissances existaient deux types de contenus : les articles et les tutoriels, et chacun avait son module spécifique. Seulement, lorsqu'un problème surgissait, il n'était pas rare qu'il ne soit corrigé que pour un seul des deux modules et que l'autre ne reçoive l'aide des développeurs que plus tard. À cette honteuse injustice s'ajoutait un écart flagrant au niveau des fonctionnalités disponibles : la ZEP-03 se restreignait aux tutoriels, ces derniers se voyaient dédier des galeries, pouvaient être placés en bêta pour recevoir les commentaires d'autres membres… Bref, les auteurs d'articles se mirent à bougonner, de manière assez compréhensible toutefois.

Épris d'égalité et à l'âme pacifiste, deux courageux (ou fous, selon les points de vue) développeurs, artragis et pierre_24, se mirent alors en tête de remédier au conflit : ainsi naquit la ZEP-12, le 24 juillet 2014.

Pour ceux qui vivraient dans une grotte, une ZEP est un texte écrit par un membre de la communauté (n'oublions pas que c'est uniquement cette dernière qui fait vivre le site) et dont l'objectif est de spécifier « une amélioration de Zeste de Savoir voulue par la communauté », comme l'explique la ZEP-01. Pour le moment, quatre ZEPs ont déjà été complètement implémentées : la ZEP-03, introduisant une page d'aide aux auteurs, les ZEP-17 et 23, spécifiant respectivement l'API des membres et des MPs, et la ZEP-04, décrivant la page d’accueil. Mais bien d'autres sont en cours et n'attendent que votre participation.

Revenons-en à la ZEP-12. Suite à son ouverture, de nombreuses discussions ont eu lieu, parfois orageuses, lesquelles ont débouché sur un compromis au niveau de la spécification. Le développement de la ZEP-12 a alors débuté, en janvier 2015, puis s'est déroulé durant tout le printemps au gré des disponibilités de chacun. Hugo est venu donner un coup de main fort appréciable durant cette période, et sans lui, la ZEP-12 aurait probablement pris encore plus de retard. Le code a pu être testé plusieurs fois, grâce à l'aide inestimable de Vayel et d'Eskimon.

Début juillet, la ZEP-12 est entrée dans une phase de correction de bugs. Imaginez un peu : l'ampleur de la modification dépassait tout ce que Zeste de Savoir avait pu connaitre jusqu'ici, et le serveur de bêta a dû être mis à contribution pendant plus d'un mois pour s'assurer, grâce au courageux Sandhose, que tout allait bien se passer lors de la mise en production, et ce, chers agrumes, afin que vous ne perdiez pas vos repères, mais aussi pour que l'expérience du site soit vraiment améliorée. Et c'était plus que nécessaire, puisque plusieurs dizaines de bugs ont pu être détectés, entre autres par firm1 et Andr0, et corrigés dans la foulée. Cette phase était plus que critique et nécessaire. Par exemple, au début, la migration avait échoué sur la plupart des articles, rendant la bêta completement innaccessible.

Et finalement, au terme de 1000 commits¹ comptabilisant plus de 15 000 lignes de code modifiées², la ZEP-12 a été intégrée au code de Zeste de Savoir le 17 septembre 2015 !

Et même avec ça, plus de 50 bugfixes ont dû être réalisés, poussant le nombre de releases candidates³ à 5 (quand on vous dit que la bêta, ça sert à quelque chose) ! Autant dire que cela a demandé énormément d'investissement de la part de l'équipe de dev.

Avec cette implémentation de la ZEP-12, toute nouvelle fonctionnalité et tout bug seront corrigés immédiatement au niveau des tutoriels et des articles, puisque ceux-ci appartiennent désormais au même module. Mais ce n'est pas tout : une multitude de fonctionnalités à croquer ont fait leur apparition. On y jette un coup d'oeil ?

Que s'est-il passé ?

Un travail de fond …

Beaucoup de travail a tout d'abord été fait sur le code en lui-même, avec assez peu de résultats visibles par les membres, mais essentiels pour la suite du développement.

En effet, comme énoncé plus haut, la ZEP-12 part du constat qu'un article et un tutoriel ont énormément de propriétés en commun, et qu'il n'y avait donc pas de raison de les traiter différemment. Il était donc d'une part nécessaire de repenser les modules pour qu'ils ne fassent plus qu'un. But du jeu : aucune duplication. Ce qui a été réalisé permettra donc dans le futur d'implémenter plus facilement des fonctionnalités, qui seront directement disponibles pour les articles et les tutoriels. Le code est même assez souple pour pouvoir accueillir d'autres types de contenus, tels que des tribunes libres. Il s'agit donc bien en premier lieu de faciliter la vie des développeurs.

Par ailleurs, vous n'êtes pas sans savoir que notre module de rédaction utilise le célèbre gestionnaire de version Git. Pour les auteurs, cela se traduit par la possibilité de comparer différentes modifications apportées, via l'outil d'historique des versions :

L'ancien module avait également pour défaut de stocker les informations deux fois : une fois en base de données et une autre dans des fichiers, ce qui a entraîné par le passé des bugs dont la correction n'était pas très satisfaisante. Il a donc été choisi de se reposer sur Git (et donc le stockage sur le disque) dès que cela était possible et de soulager la base de données tout en profitant des fonctionnalités offertes par le gestionnaire de version. Toutefois, cette option a un défaut : elle requiert un nombre important d'opérations de lecture/écriture (IO, pour les programmeurs) sur le disque, lesquelles sont relativement coûteuses en temps. Une attention particulière a donc dû être portée sur ce point, même si des améliorations sont probablement encore possibles. À priori, les performances de ce nouveau module sont mêmes équivalentes à celles de l'ancien.

Toutes ces modifications n'ont pas été sans mal et, par exemple, le module de recherche a dû être repensé pour coïncider avec cette nouvelle philosophie. En effet, ce module ne permettait initialement pas d'indexer des fichiers, quasiment utilisés exclusivement par le nouveau module rédactionnel. Hugo est donc passé par là et a amélioré avec brio la recherche de contenus.

… Et de forme !

Mais les avantages de la ZEP-12 ne se restreignent pas aux développeurs, et les auteurs gagnent également au change. En effet, puisque la mission de Zeste de Savoir est de « promouvoir le partage de connaissances à travers des ressources pédagogiques gratuites », il est essentiel de proposer un module qui soit le plus efficace et simple d'utilisation possible. Dès lors, et sans être exhaustif, nous avons le plaisir de vous présenter les fonctionnalités introduites par ce module tout neuf et dont les auteurs pourront bénéficier directement.

Premièrement, une grande vague d'uniformisation de l'interface et des fonctionnalités a eu lieu : tous les contenus possèdent une galerie, tous peuvent être mis en bêta et tous bénéficient de la page d'aide aux auteurs.

Quelques changements sont aussi à noter du côté de la structure des contenus. Tout d'abord, le mot « section » remplace désormais le terme « extrait », le premier étant plus simple à appréhender. Par ailleurs, un article peut désormais contenir plusieurs de ces sections, comme vous avez pu le constater en ce moment même. Ce découpage rend plus facile l'édition, permet un meilleur référencement et donne droit à la création d'un sommaire¹. À noter que durant le processus de migration vers la ZEP-12, un script s'est chargé de repérer tous les titres présents dans les articles et de découper ceux-ci en sections : vous n'avez qu'à admirer le résultat !

En outre, les contraintes sur la structure se sont considérablement assouplies. Désormais, vous disposez de trois types de conteneurs : les parties, sans parents et avec un ou des enfants, les chapitres, avec un parent (une partie) et des (ou un) enfants, et les sections, sans enfant. À partir de là, vous pouvez créer, supprimer et déplacer des conteneurs comme il vous sied, du moment que vous respectez les contraintes d'imbrication (une partie contenant un chapitre comportant une section ne peut être déplacée en tant qu'enfant, ce qui créerait une conteneur de niveau 4). Notamment, il est possible de créer des moyens-tutos, ainsi que des tutoriels hybrides :

1
2
3
4
5
6
7
8

+ Partie 1 
    + Section 1.1
    + Section 1.2 
    + Section 1.3 
+ Partie 2
    + Chapitre 2.1
        + Section 2.1.1
        + ...

Par contre, un conteneur est homogène. Le cas suivant ne fonctionne donc pas.

1
2
3
4

+ Partie
    + Chapitre
        + Section
    + Section

Vous pouvez donc laisser libre cours à votre imagination et à votre créativité, même si l'équipe de validation n'acceptera pas les abus de déstructuration des contenus. Il faut en effet garder une cohérence dans ses écrits et l'équipe bénévole est là pour veiller au grain !

Tant qu'on en est aux bonnes nouvelles, sachez également que l'édition externe est beaucoup plus simple, car l'import d'archives a été fortement amélioré. Comme vous pouvez le constater par vous-même, il est désormais possible d'importer une archive pour créer un nouveau tutoriel ou article, mais également pour le mettre à jour (et contrairement à l'ancien système, la structure n'a pas à être identique). Et pour faciliter encore un peu la possibilité d'édition externe, on peut désormais importer directement les images avec le contenu, et le texte sera mis à jour en conséquence.

Il est alors tout à fait possible de créer un éditeur externe qui génèrerait directement ladite archive à importer ensuite sur le site. Avis aux amateurs !

Finissons ce petit tour d'horizon, avec l'amélioration des fonctionnalités de déplacement grâce à un travail monstre effectué par artragis, ce qui permet désormais de déplacer les sections entre chapitres, mais aussi de déplacer les chapitre eux-mêmes, dans la limite du possible ! Si vous aviez un big-tuto que vous aimeriez transformer en moyen-tuto, c'est possible grâce à cette fonctionnalité !

En vrac, on peut encore citer une amélioration du processus de publication (avec, entre autre, un système pour que les publications qui ont échoué n'affectent plus les versions déjà en ligne), un nettoyage de certaines erreurs générées par le précédent module, et d'autres que vous pouvez retrouver dans la documentation du module (qui décrit de manière plus complète la philosophie et les implications de ce nouveau module).

Afin de faciliter les retours sur ce nouveau module sans pourrir les commentaires ci-dessous, deux sujets ont été créés :

• Ce sujet vous permettra d'échanger sur cette nouvelle fonctionnalité : si vous avez des suggestions d'amélioration ou des choses que vous n'aimez pas, c'est là qu'il faudra se manifester.
• Ce sujet vous permettra uniquement de faire part de problèmes induits par la migration. En effet, certains contenus ont pu être mal migrés (même si un maximum a été fait pour que ça n'arrive pas). Il vous permettra d'avoir un contact direct avec les personnes capables de corriger les éventuelles erreurs, et doit donc être employé uniquement à cet effet !

Vers l'infini et au delà !

Un mieux, mais seulement un début

Même s'il s'agit déjà là d'une grande avancée dans le code de Zeste de Savoir, il reste encore bien des choses à faire, et ce module sera probablement amené à encore bien évoluer.

En effet, il n'est pas exempt de défauts, qui sont autant de choix ayant dû être faits (même s'il a parfois été difficile de les respecter). Par exemple, il a déjà été mentionné que se baser sur la lecture et l'écriture de fichiers est un point critique. Notamment, il est nécéssaire de créer un fichier par section, ce qui requiert autant de lectures lorsque celles-ci doivent être affichées. Par ailleurs, la phase de résolution d'URL (trouver quoi afficher en fonction de l'adresse demandée) ne repose plus sur la base de données et nécessite donc systématiquement la lecture du fichier contenant la structure du contenu (le manifest.json).

De même, la ZEP-12 n'apporte pas de réelle révolution dans l'interface. Ainsi, pour la majorité des utilisateurs, le travail réalisé sur le fond semblera invisible, peut être même insuffisant. Ce travail de fond était d'une ampleur si importante que malgré neuf mois de développement, certaines killer features tant pour l'interface que pour la vie du site n'ont pas pu être développées, à notre grande frustration.

Comptons aussi le fait que transposer puis améliorer certaines fonctionnalités telles que le déplacement a pris tellement de temps que nous n'avons pas pu les pousser jusqu'au bout. Ainsi, vous pouvez déplacer un élément avant ou après un autre mais pas dans un nouveau parent. Autrement dit, si vous voulez déplacer une section dans un nouveau chapitre, il faut créer le chapitre, lui ajouter une section vide et déplacer la section désirée avant/après cette dernière.

Le plus gros problème, en terme d'interface, restera que pour vous donner la possibilité de faire un tutoriel moyen et autres structures plus souples, nous avons retiré le champ qui auparavant vous permettait de sélectionner "mini tuto" ou "big tuto". Cela signifie que nous ne vous guidons plus dans la rédaction d'un contenu.

Ce manque de "révolution" se fera aussi sentir du côté des validateurs qui feront encore face à de longues attentes lors de la publication d'un gros tutoriel.

Il a par ailleurs été très difficile de maintenir les propriétés ACID (deux objets ne peuvent pas porter le même nom par exemple) et le référencement concernant ce module (par exemple, toutes les URLs de vos contenus ont changé, et des redirections ont dû être mises en place afin que les anciennes soient toujours valides).

Une fenêtre sur le monde

Sur une note plus positive, plusieurs ZEP attendaient tranquillement l'implémentation de la douzième du nom, ce qui est désormais chose faite.

• La ZEP-05, qui doit améliorer l'exportation de nos contenus en PDF, HTML ou EPUB, point qui n'a pas du tout été touché durant la ZEP-12 ;
• La ZEP-08 , qui s'interoge sur l'usage de fonctionnalités plus avancées de Git pour encore améliorer l'édition ;
• La ZEP-11, qui implémenterait des statistiques pour l'auteur ;
• La ZEP-13, qui se propose d'ajouter un troisième type de contenu, les "tribunes" ;
• Les ZEPS 16 et 20, qui sont des initiatives pour améliorer le confort de validation via la relecture par des pairs et la proposition de corrections ;
• La ZEP-24, qui permettrait de repenser les notifications de manère plus efficace, actuellement en développement par Taguan ;
• La ZEP 15, qui tente de repenser la manière dont on navigue entre les contenus ;
• Les ZEP 31 et 32, qui cherchent à connecter les contenus entre eux ;
• Les ZEPs 33 et 34, qui visent à guider les auteurs dans la création de leurs contenus.

Autant de sujets qui n'attendent que votre avis et votre aide.

Enfin, cette ZEP nous a permis de mettre à jour d'autres chantiers très importants pour le site tels que :

• La validation partielle des contenus (on ne propose à la validation qu'une partie d'un tutoriel) ;
• Une forte amélioration de l'éditeur du site ;
• Une meilleure présentation des pages communautaires (bêta, page d'aide).

Zeste de Savoir n'a qu'un an et continue de prendre son envol, la ZEP-12 n'est ici qu'un souffle favorable à celui-ci, mais quel souffle !

Si vous êtes curieux, vous pouvez également retrouver la liste complète des modifications apportées par cette release, finalement numérotée "12.0"¹ :

• La ligne éditoriale officielle de Zeste de Savoir
• Les injections SQL