| Cartouche | |
|---|---|
| ZEP | 32 |
| Titre | Connexion des contenus - les relations |
| Révision | 3 |
| Date de création | 13/05/2015 |
| Dernière révision | 29/09/2015 |
| Type | Feature |
| Statut | Rédaction |
Aujourd'hui, le contenu sur Zeste de Savoir se résume à une liste de tutoriels et d'articles ne partageant rien de plus que des auteurs et des tags. Très peu d'informations donc rendent compte de la manière dont ils interagissent.
Cette ZEP cherche à pallier ce manque afin d'aider les lecteurs à naviguer parmi les contenus. À cet effet, nous souhaitons établir des liens entre les contenus, pour rendre compte de leurs relations.
Dans la suite, le terme « tuile » désignera un contenu (tutoriel, article, chapitre, message sur le forum, etc. : ça reste à spécifier) qu'on peut connecter aux autres.
Pour ceux qui se demanderaient comment se positionne cette ZEP par rapport à celle sur les parcours, l'objectif ici est de créer une carte IGN, tandis que les parcours font office de voyages organisés.
Notion de relation
Que signifie « être en relation » pour deux tuiles ?
Tout simplement, qu'il existe une raison, peu importe laquelle, qui permet de les rapprocher, de les relier. Cette raison peut être un auteur en commun, une date de publication identique, des tags partagés, un même sujet (les fonctions en Python), un même thème (Python), une longueur de titre identique, le fait que l'un est nécessaire à l'autre, aide à comprendre l'autre… Bref, c'est très vague et c'est pourquoi il faut spécifier cela.
Pour deux tuiles données, il existe alors deux possibilités de rendre compte des relations les connectant :
- Une liste de tout ce qui nous passe par la tête et qui les mette en relation (cf. énumération précédente) ;
- Une liste de relations satisfaites parmi un nombre fini de relations déterminées.
La première solution permettrait de rendre compte en détails des relations entre deux extraits mais poserait deux problèmes : certaines informations seraient superflues et ce système serait pas assez stricte pour être exploitable automatiquement par la suite. Effectivement, cette méthode reviendrait à commenter ses fonctions comme suit.
1 2 3 4 5 6 7 8 | def f(arg1, arg2): """L'argument arg1 est un entier naturel représentant le nombre d'orteils pourris de la grand-mère considérée. Le second argument, arg2, désigne quant à lui le nom de ladite grand-mère, sous forme d'une chaîne de caractères. """ print("La grand-mère {} a {} orteils pourris.".format(arg2, arg1)) |
Demandez à Sphinx1 de gérer des docstrings2 de ce type et il va vous cracher à la figure.
Il semble donc préférable de définir un nombre fini de relations possibles, ce qui permettrait par exemple d'effectuer du tri (liste des tuiles nécessaires à untel, du même auteur, etc.), de générer des parcours (cf. ZEP-31) personnalisés… Cette seconde méthode s'apparente à :
1 2 3 4 5 6 7 8 9 10 | def f(arg1, arg2): """ :param arg1: Nombre d'orteils pourris de la grand-mère :param arg2: Nom de la grand-mère :type arg1: int :type arg2: str """ print("La grand-mère {} a {} orteils pourris.".format(arg2, arg1)) |
Là, Sphinx est beaucoup plus courtois (et efficace !).
Il semble donc judicieux de se restreindre à un nombre fini de relations rigoureusement déterminées. Dans la suite, nous utiliserons le formalisme des relations binaires, qui fournit une manière rigoureuse de décrire les relations ainsi que de bénéficier d'un certain nombre d'outils mathématiques (notion de maximum pour les relations d'ordre, de classe d'équivalence pour celles d'équivalence, etc.).
Les relations à proprement parler
Prenons $A$ et $B$ deux tuiles quelconques et inspirons-nous de ce message de SpaceFox pour définir les rapports entre les tuiles à mettre en valeur, et via quelles relations.
Quelles tuiles lire avant celle courante ?
- Nécessité
$A$ est en relation avec $B$ si la compréhension de $A$ est nécessaire à celle de $B$. Cette relation binaire est transitive.
Elle permettrait de dresser la liste des tuiles constituant des pré-requis pour une autre.
- Utilité (accessoires)
$A$ est en relation avec $B$ si la compréhension de $A$ est utile à celle de $B$, sans pour autant lui être nécessaire. Cette relation est transitive.
Elle permettrait de lister les tuiles aidant à la compréhension mais demeurant facultatives.
- Similarité
$A$ est en relation avec $B$ si $A$ et $B$ véhiculent les mêmes connaissances. Cette relation est réflexive, transitive et symétrique. C'est donc une relation d'équivalence. Par exemple, s'il existe deux tuiles sur les variables en Python (parce que l'auteur de la plus récente n'était pas satisfait de la plus ancienne), celles-ci seraient marquées comme similaires.
Elle interviendrait quand deux personnes souhaitent expliquer une même chose de deux manières différentes et permettrait d'éviter de « doubler » les pré-requis. Pour reprendre l'exemple, je n'aurais à consulter qu'une seule des deux tuiles à propos des variables pour satisfaire le pré-requis de la tuile sur les fonctions.
Quelles tuiles lire après celle courante ?
- Paternité (cross-selling)
$A$ est en relation avec $B$ si $A$ et $B$ possèdent un auteur en commun. Cette relation est réflexive, transitive et symétrique. C'est donc une relation d'équivalence.
Elle remplirait le rôle de la section « Du même auteur » qu'on rencontre dans les bouquins. En effet, même si c'est plus rare pour du contenu technique, il est possible qu'un lecteur soit intéressé par des textes partageant le même style d'écriture, la même pédagogie que celui consulté. Ces conditions sont généralement réunies quand il y a un auteur commun.
- Thématique (cross-selling)
$A$ est en relation avec $B$ si $A$ et $B$ partagent un même tag. Cette relation est réflexive, transitive et symétrique. C'est donc une relation d'équivalence. Par exemple, à la fin d'un tutoriel sur les décorateurs en Python, on est probablement intéressé par d'autres fonctionnalités du langage.
- Approfondissement
$A$ est en relation avec $B$ si $A$ approfondit les connaissances diffusées par $B$. C'est une relation transitive et antisymétrique. Par exemple, un extrait sur les décorateurs en Python est un approfondissement d'un extrait sur les fonctions en Python.
Si $A$ approfondit $B$, $B$ est obligatoirement nécessaire à $A$. Toutefois, la réciproque est fausse. En effet, il est nécessaire en Python de connaître la notion de variable pour assimiler celle de fonction, mais cette seconde n'approfondit pas la première au sens strict. En revanche, une tuile allant plus loin dans l'explication de notion de fonction (par exemple, une fonction est un objet quelconque, on peut donc en passer en paramètre d'autres fonctions ; dans un cours destiné aux débutants, une telle information ne serait pas mentionnée) approfondirait la précédente.
De plus, si $A$ approfondit $B$, $A$ partage nécessairement un tag avec $B$. Mais là aussi, la réciproque est fausse. En effet, « Les espaces vectoriels » et « Les développements limités » partageraient le tag « Mathématiques », mais aucun n'approfondit l'autre.
- Remplacement (remplacement)
$A$ est en relation avec $B$ si $B$ est obsolète et que $A$ se substitue à lui. C'est relation est transitive. Par exemple, un tutoriel sur PDO serait en relation avec un tutoriel sur mysqli.
Elle permettrait, une fois une tuile désuète lue, de se mettre à jour en consultant son homologue moderne. On peut aussi ranger cette relation dans la catégorie précédente, puisqu'elle permettrait carrément de ne pas lire la tuile périmée.
Administration
Seule l'équipe de validation a le droit de créer, modifier et supprimer des relations. Elle devra bénéficier d'une interface pour cela.
Quand une relation est supprimée, tous les liens correspondants le sont également, et les auteurs des tuiles affectées reçoivent une notification.
Il faut également un moyen de prévenir les personnes créant les liens de l'ajout d'une relation, qu'elles puissent utiliser cette dernière pour connecter les tuiles.
Mise en relation
Se référer à la ZEP-35.
Merci.
PS : les commentaires relatifs à cette révision commencent ici.
-
Sphinx est un générateur automatique de documentation pour Python : à partir des commentaires que vous faites dans le code, il génère de beaux fichiers PDF, Markdown et compagnie. ↩
-
Une docstring est un commentaire permettant de décrire une fonction : type et signification des arguments, de la valeur de retour, rôle de la fonction, exceptions levées, etc. ↩
