Etat de l'art du module des tutoriels

Qu'est ce qui a été pensé pour la v1

L'auteur de ce sujet a trouvé une solution à son problème.
Staff
Auteur du sujet

Bonjour à tous,

J'ouvre ce topic pour présenter globalement (impossible de rentrer dans les détails les plus obscurs) l'état de l'art du module des tutoriels tel qu'il a été prévu pour une v1. Etant donné que je suis à l'origine de son développement dès le départ, je pense avoir emmagasiné le plus d'info la dessus. Je me suis rendu compte que certains développeurs qui sont rentrés dans le projet récemment ont du mal à voir comment on a décidé de démarrer pour une v1 et vers ou est-ce qu'on veut évoluer.

Pourquoi tout n'est pas versionné aujourd'hui ? Pourquoi utiliser la base de données en plus des dépots git ? Pourquoi on ne peut pas encore rédiger en offline ? Bref, tout un tas de questions que j'essayerai de détailler en expliquant ce que devrait être le module des tutoriel dans une v1. Si ce n'est pas le cas aujourd'hui, il s'agit d'un bug tout simplement.

NB : N'hésitez pas à utiliser ce thread pour poser des questions sur les tutoriels, ça centralisera donc les informations

Les composantes d'un tutoriel

Un tutoriel n'est qu'un ensemble d'introduction de corps et de conclusion. Cependant, selon la taille souhaitée du tutoriel, il peut nécessiter une organisation particulière. C'est pourquoi les tutoriel de ZdS sont structurés en quatre niveaux.

Niveau 1 : Le tutoriel

Ce niveau définit l'ensemble des métadonées assocciées à un tutoriel, c'est le plus haut niveau de touts les tutoriels. on y retrouve les informations suivantes :

  • titre
  • description
  • logo
  • licence
  • sous-catégories
  • introducton
  • conclusion

Niveau 2 : La partie

Ce niveau adapté à des documents un peu plus longs, permet de subdiviser notre contenu en plusieurs parties. C'est typiquement le niveau qui sera utile si vous souhaiter rédiger un mémoire, ou une thèse. Par contre, pour un simple article, ce n'est pas la peine d'en faire des parties. Un tutoriel peut contenir plusieurs parties et une partie comprend essentiellement les informations suivantes : - titre - introduction - conclusion - position (dans le tutoriel)

Niveau 3 : La chapitre

On retrouve la encore les mêmes notions qu'on peut rencontrer dans la rédaction d'un document pédagogique. Si une partie peut contenir plusieurs chapitres (on le verra plus loin dans le cas des bigtutos), un chapitre peut être rattaché a un tutoriel directement (minituto) . Le chapitre comprend les informations suivantes : - titre - introduction - conclusion

Niveau 4 : L'extrait

L'extrait est la niveau le plus fin de subdivision d'un tutoriel. Il constitue le contenu, ou encore le corps de notre texte. Un extrait est constitué uniquement d'un bloc de texte.

Les types de tutoriels

Il existe actuellement deux types de tutoriels, les minituto et les bigtutos, Même s'il y'a une réflexion sur la création de moyen-tuto, laissez moi déjà vous présenter ce qui existe aujourdhui.

Les minitutos

Un minituto est un format de tutoriel pour du contenu léger. Fonctionnellement il s'agit d'un tutoriel qui ne contient qu'un seul chapitre (niveau 3) mais peut contenir un ou plusieurs exrait. On pourrait le représenter ainsi :

1
2
3
4
5
6
7
8
9
Tutoriels  -> chapitre  -
                        |-> introduction
                        |-> 
                        |-> extrait 1
                        |-> extrait 2
                        |-> extrait ...
                        |-> extrait n
                        |-> 
                        |-> conclusion

Dans ce cas, le nombre de chapitre est bien limité à 1 et la présentation d'un minituto consiste à présenter un seul chapitre de la structure globale.

Les bigtutos

Un bigtuto, si on repense à nos niveaux de structure, une un tutoriel dans lequel on peut avoir plusieurs parties, chaque partie pouvant contenir plusieurs chapitres et chaque chapitre pouvant à leur tour contenir plusieurs extraits. Les big tutos reprenent donc ici tous les éléments de la structure. Ce format est adapté aux tutoriels donc le contenu est assez conséquent, et demande beaucoup de structuration. On pourrait le représenter ainsi:

 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
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
Tutoriels -
          | -> partie 1 -
                        |-> chapitre 1 -
                                       |-> introduction
                                       |-> extrait 1
                                       |-> extrait 2
                                       |-> extrait ...
                                       |-> extrait n
                                       |-> conclusion
                        |-> chapitre 2 -
                                       |-> introduction
                                       |-> extrait 1
                                       |-> extrait 2
                                       |-> extrait ...
                                       |-> extrait n
                                       |-> conclusion
                        |-> chapitre n -
                                       |-> introduction
                                       |-> extrait 1
                                       |-> extrait 2
                                       |-> extrait ...
                                       |-> extrait n
                                       |-> conclusion
          | -> partie 2 -
                        |-> chapitre 1 -
                                       |-> introduction
                                       |-> extrait 1
                                       |-> extrait 2
                                       |-> extrait ...
                                       |-> extrait n
                                       |-> conclusion
                        |-> chapitre 2 -
                                       |-> introduction
                                       |-> extrait 1
                                       |-> extrait 2
                                       |-> extrait ...
                                       |-> extrait n
                                       |-> conclusion
                        |-> chapitre n -
                                       |-> introduction
                                       |-> extrait 1
                                       |-> extrait 2
                                       |-> extrait ...
                                       |-> extrait n
                                       |-> conclusion
          | -> partie n -
                        |-> chapitre 1 -
                                       |-> introduction
                                       |-> extrait 1
                                       |-> extrait 2
                                       |-> extrait ...
                                       |-> extrait n
                                       |-> conclusion
                        |-> chapitre 2 -
                                       |-> introduction
                                       |-> extrait 1
                                       |-> extrait 2
                                       |-> extrait ...
                                       |-> extrait n
                                       |-> conclusion
                        |-> chapitre n -
                                       |-> introduction
                                       |-> extrait 1
                                       |-> extrait 2
                                       |-> extrait ...
                                       |-> extrait n
                                       |-> conclusion

Cycle de vie des tutoriels

Quelque soit le type de tutoriel, le cycle de vie de celui-ci reste toujours le même. Un tutoriel peut-être rédigé par un ou plusieurs auteurs. Chaque modification sur le tutoriel est conservée afin de pouvoir retrouver l'historique des modifications et éventuellement recupérer le contenu perdu. Lorsqu'un tutoriel est crée il rentre dans sa première étape.

Le brouillon

Le brouillon est la première étape du cycle de vie d'un tutoriel. Il donne toujours l'état le plus récent du contenu d'un tutoriel vu par les auteurs. Chaque fois que le contenu du tutoriel est modifié, c'est la version brouillon qui est mise à jour. La version brouillon est accessible uniquement pour les auteurs et validateurs d'un tutoriel, Si on souhaite donner un accès en lecture seule à nos écrit, il faut passer par la méthode adéquate.

La beta

Lorsque les auteurs estiment que leur tutoriel est arrivé à un certain niveau de maturité, et qu'ils souhaitent recuillir les premiers retours de lecteurs, ils se doivent de mettre à disposition de la communauté le tutoriel en lecture seule. C'est le mode beta.

La procédure voudrait que lors de l'ouverture d'une beta, l'auteur crée un sujet dans le forum des tutoriels en beta, en postant le lien version la version beta du tutoriel.

Le lien de la beta, peut être trouvé via votre profil utilisateur, vous devez recopier tout le lien avec la partie ?version=blablabla. Et pensez bien à modifier ce lien lorsque vous mettez à jour votre version beta.

En fait lorsqu'un tutoriel est en mode beta, il s'agit d'une version précise qui est mise dans ce mode. On peut continuer à mettre à jour la version brouillon pour rajouter de nouveaux chapitres à notre tutriel, pendant ce temps, la communauté lit une version figée de notre tutoriel. L'avantage étant que si le tutoriel prend beaucoup de temps à lire, le lecteur n'a pas de mauvaise surprise de mise à jour pendant sa lecture. Les auteurs quant à eux doivent mettre à jour manuellement leur version beta et ainsi ils controllent pleinement ce qu'ils mettent à disposition des lecteurs.

La validation

Une fois que l'auteur a eu assez de retour sur son tutoriel, et qu'il estime qu'il est prêt à être publié, il décide d'envoyer son tutoriel en validation.

L'envoi en validation n'est pas définitif, dans le sens ou, vous pouvez à tout moment mettre à jour la version qui se trouve du coté des validateurs. Evitez d'en abuser tout de même, car, si un validateur commence à lire votre tutoriel, il devra recommencer son travail si vous faites une mise à jour dessus. Ce qui pourrait non seulement ralentir le processus de validation de votre tutoriel, mais décourager aussi le validateur. Donc si je dois vous donner un conseil, c'est de n'envoyer que du contenu sur en validation.

Comme pour la beta, la version brouillon du tutoriel peut continuer à être améliorée pendant que la version de validation reste figée. Auteurs et validateurs peuvent donc continuer à travailler chacun de son coté.

La publication

Une fois le contenu, lu et relu par l'équipe staff, le tutoriel est publié. Il faut bien préciser que le processus de validation peut être assez long en fonction de la taille du tutoriel traité. Un tutoriel n'est pas obligé d'être publié à la suite d'une demande de validation, il peut aussi être rejeté. Dans tout les cas, un historique de validation est disponible pour les membres du staff.

La publication d'un tutoriel entraine la création d'export en plusieurs formats. On a les formats

  • Markdown : disponible uniquement pour les membres du staff et les auteurs des tutoriels
  • HTML
  • PDF
  • EPUB : format de lecture adapté aux liseuses
  • Archive : un export de l'archive contenant le dépot git du projet.

Pour différentes raisons, il se peut que l'export dans divers formats échoue. Dans ce cas, le lien de téléchargement n'est pas présenté. Un fichier de log sur le serveur enregistre les problèmes lié à l'export d'un format.

Aujourd'hui il existe des bugs dans la conversion en PDF (blocs custom), qui devront être réglés plus tard avec la ZEP 05

L'aspect technique

Comment tout ce ci est stocké dans la base de données ?

Aujourd'hui la base de données est utilisée comme zone tampon, surtout parce que Django propose déjà des methodes d'enregistrement des objets en base de données de manière concurrentes et thread safe. L'idée étant de s'en détacher à terme. La version stockée dans la base de données est le dernier état, c'est à dire l'état de la version en brouillon. Il ne faut donc pas aller chercher en base de données les informations pour les afficher.

Chaque tutoriel possède trois attributs principaux :

  • sha_draft : le hash du commit de la version brouillon
  • sha_beta : le hash du commit de la version brouillon
  • sha_validation : le hash du commit de la version validation
  • sha_public : le hash du commit de la version publique

On peut les voir comme des pointeurs sur chaque version, et le fait qu'ils soient stockés en base les rends plus accessibles. A terme aussi, on devrait pouvoir en faire des branches.

Il faut aussi noter qu'on ne stocke pas le contenu (introduction, conclusion, extrait) directement en base de données, on stocke uniquement les chemin relatif vers le fichiers markdown qui contiennent le contenu.

Qu'est ce qui est versionné et donc tracés ?

Le module des tutoriels se base sur git pour versionner son contenu. Physiquement, nous avons un répertoire pour chaque tutoriel (point d'initialisation du dépot). A l'intérieur nous avons un répertoire par partie, et dans chaque partie, un répertoire par chapitre, et pour chaque chapitre, un fichier par extrait.

Pour éviter les conflits dans les noms de fichier, le chemin vers un extrait aura souvent le modèle suivant :

[id_partie]_[slug_partie]/[id_chap]_[slug_chap]/[id_extrait]_[slug_extrait].md

Pour pouvoir versionner tout ceci, nous avons un fichier nommé masnifest.json chargé de stocker l'ensemble des métadonnées versionnées du tutoriel. Ce fichier manifest est lui aussi versionné. Pour chaque version, il suffit donc de lire ce fichier pour reconstituer un tutoriel. C'est un fichier json qui reprend la structure du document, et les différents chemins relatifs vers le contenu. Les métadonnées stockées sont :

  • Le titre du tutoriel, des parties, des chapitres et des extraits
  • Le sous-titre du tutoriel
  • La licence du tutoriel
  • Les divers chemin relatifs vers les fichiers markdown

L'objectif étant d'arriver à tout versionner (catégories, …) et de ne plus avoir à lire dans la base de donnée pour afficher quelque chose.

Qu'en est-il des images ?

Le versionning des images d'un tutoriels (celles qui font partie de la gallerie du tuto) a fait l'objet d'un vrai débat à l'époque, et j'ai (je parle bien en mon nom ici) décidé finalement de ne pas les versionner dans un premier temps, pour des raisons simples : - versionner les images peut rendre très rapidement une archive lourde si l'auteur change beaucoup d'images, il va se trouver avec des images plus jamais utilisées qui traine dans son archive. - avoir besoin d'interroger le dépot à chaque fois pour lire les images peut rapidement devenir lourd pour la lecture.

J'ai donc pris le parti de ne pas versionner les images qui sont stockées sur le serveur, ce n'est pas critique et on peut très bien travailler ainsi. Par contre, il faudra mieux y réfléchir pour une version 2 afin de proposer la rédaction totalement en mode hors ligne.

Quid des tutoriels publiés ?

Les tutoriels en offline sont tous versionnés, et sont dans le répertoire tutoriels_private. Lorsqu'ils sont validés le traitement suivant les appliqué.

  • On copie le dépôt du tutoriel dans le répertoire tutoriels_public
  • On va chercher dans l'historique du dépot les fichiers correspondant à la version à publique
  • On converti ces fichiers en html (en utilisant zMarkdown)
  • On stocke les fichiers html sur le serveur.

Ainsi, pour lire un tutoriel public, on a juste besoin de lire les fichiers html déjà convertis.


J'espère ne pas avoir été trop incomplets, mais je tenais à clarifier un bon nombre de chose pour aider les contributeurs qui ont du mal à aborder le module des tutoriels.

Notons aussi que les articles fonctionnent un peu dans la même logique, mais les tutoriels ont été mieux traités que les articles, et donc on trouveras peut-etre plus de bugs du coté des articles.

Édité par firm1

Super résumé, ça aide a y voir plus clair !

Je me pose cependant une question…
En soit un article est l’équivalent d'un minituto (0 parties, 1 chapitre, n extrait). Pourquoi la différenciation tuto/article ne pourrait pas être faite via un simple booléen et ainsi factorise pas mal de code ?

(je me doute qu'il y a surement une bonne raison, seulement je ne l'ai pas encore saisi)

Édité par Eskimon

ZdS, le best du Zeste ! Tuto Arduino, blog, etc

+0 -0
Staff
Auteur du sujet

En soit un article est l’équivalent d'un minituto (0 parties, 1 chapitre, n extrait)

Actuellement un article n'a qu'un seul extrait alors qu'un mini tuto peut en avoir plusieurs. Donc un boolean ne peut pas trop gerer ça, mais on peut en effet factoriser du code.

Encore des trucs que j'avais prévu de faire, mais uniquement post v1. La factorisation est naturelle une fois que le tout est stabilisé.

Ou tout simplement

Tu me met une explication bien complexe par rapport à un simple tag à mettre à jour… ta solution me paraît pas très simple, rien parce que :

si on détecte que le hash demandé appartient bien à l' historique

Imagine toi un gros tuto avec 1000 commits… tu vas attendre 5 minutes avant de savoir si c'est bien dans l'historique.

Staff
Auteur du sujet

Qu'en est-il du refactoring des tutos pour permettre les "moyens tutos" et la transition d'un mini-tuto à un big tuto ?

Gwenn

Comme je l'ai précisé dans le premier post, ça ne nécessite pas vraiment de refactoring. Il y'a juste une étape de factorisation de 2-3 fonctions à faire, et on pourra mettre a disposition des tutos au format moyen.

Si je m'en occupe, ça devrait prendre environ 24h de développement (a étaler sur mon temps libre).

Voila, grosso modo ce qu'on peut en dire.

Il faut aussi noter qu'on ne stocke pas le contenu (introduction, conclusion, extrait) directement en base de données, on stocke uniquement les chemin relatif vers le fichiers markdown qui contiennent le contenu.

… Des versions drafts. D'où question, quel utilité en pratique puisqu'il faut de toute façon aller pêcher dans le manifest.json pour avoir le truc à jour (et que c'est le cas dans le code … La plupart du temps) ?

Doctorant et assistant en chimie à l'Université de NamurEx-dev' pour ZdS (a aidé à réaliser la ZEP-12 !) • Carniste cis (y parait que c'est une injure)

+0 -0

Hello,

Il y a peut-être déjà une ZEP là dessus (où même la fonction existe et je ne l'ai pas trouvée):

Est-il possible de faire un export en markdown d'un tuto "brouillon" pour pouvoir continuer de l'éditer hors ligne? (Dans le cas ou un auteur veux utiliser ses temps de déplacement en train à bon escient)

Edit : une faute de frappe dans le poste original, dans la partie "La beta": "On peut continuer à mettre à jour la version brouillon pour rajouter de nouveaux chapitres à notre tutriel"

Édité par Xia

Xia, peluche olympienne |Python en s'amusant | Random xkcd

+0 -0

Du coup, vue que le système se base intégrallement sur git, il serait envisageable de permettre d'utiliser un serveur git externe (ce qui implique de désactiver l'interface en ligne ou que zds ai un accès en écriture sur le dépot) ? (au passage, la copie dans tutoriels_public devrait être un simple git clone && git checkout). De même, ça demande pas mal de travail de config, mais ne serait-il pas intéressant de donner accès directement au dépot git ? (accès en écriture/lecture pour les auteurs uniquement avec un hook pre-receive coté serveur pour rejeter tous les push qui inclueraient autre chose que des fichiers json et markdown).

Car en fait, dans l'état actuel du système je trouve dommage d'utiliser git tout en le cachant et en ne donnant pas la possibilité aux auteurs d'en utiliser toute la puissance.

Sinon, au final, je ne vois pas quel est l'intéret de la bd dans le système.

EDIT: je viens de voir que l'essentiel de mon post est traité par la ZEP-8

Édité par Nicofuma

Développeur de phpBB

+0 -0

au passage, la copie dans tutoriels_public devrait être un simple git clone && git checkout

Le pré-parsing reste inévitable pour les performances. Si tu as une version locale du site sur ton pc, je te propose de te promener un peu sur un tutoriel et de voir le temps que prend de visualiser un chapitre en version brouillon, puis de le comparer à sa version publiée. Y'à pas photo ;)

Doctorant et assistant en chimie à l'Université de NamurEx-dev' pour ZdS (a aidé à réaliser la ZEP-12 !) • Carniste cis (y parait que c'est une injure)

+0 -0

Je parlais juste de la partie "On copie le dépôt du tutoriel dans le répertoire tutoriels_public" dans cette phrase^^ Stocker une version statique du tuto publié est tout à fait logique/justifiable/bénéfique et démontrable (choisir le terme qu'on préfère :))

Développeur de phpBB

+1 -0
Staff
Auteur du sujet

Je parlais juste de la partie "On copie le dépôt du tutoriel dans le répertoire tutoriels_public"

Si je me souviens bien dans mes calcul, c'était plus long de faire un git clone -> git-checkout -> parsing que de faire une cp -> git checkout -> parsing.

Mais bon là on est dans des détails qui influent de manière très négligeables, et qu'on ne recontre que lors du clic sur le bouton de validation.

C'est possible vue que cp utilise les primitives bas niveau du système d'exploitation. Après un git clone --local devrait pour être assez rapide. Mais bon, comme tu le dis c'est négligeable et surtout anecdotique.

Développeur de phpBB

+0 -0
Vous devez être connecté pour pouvoir poster un message.
Connexion

Pas encore inscrit ?

Créez un compte en une minute pour profiter pleinement de toutes les fonctionnalités de Zeste de Savoir. Ici, tout est gratuit et sans publicité.
Créer un compte