Conventions d’écritures

Conventions d’écritures#

À propos

Les conventions d’écriture ci-dessous sont une tentative d’homogénéisation des usages qui ont émergé après multiples expérimentations avec JupyterBook, MyST, JupyterLab-Myst, etc. dans des cours à Orsay avec de grandes cohortes, dont :

C’est une première proposition qui a vocation a être discutée point par point. Retours bienvenus!

Formatage#

  • On utilise la syntaxe Markdown avec son extension MyST.

  • On utilise mdformat pour standardiser le formatage (voir détails ci-dessous).

  • Les lignes sont repliées avec une largeur de texte de 89 colonnes.

  • On utilise \ pour forcer un saut de ligne plutôt qu’un double espace en fin de ligne.

  • ~~On indente systématiquement de quatre espaces, y compris dans les listes à puces, etc.~~

Attention

mdformat et son extension mdformat-myst ont à ce jour quelques limitations :

  • pas de support pour les encarts marqués avec :::.

  • ligne vide en trop après les labels (label)=

  • écriture verbeuse des métadonnées incompatible avec jupytext.

  • indentation dans les listes à puces forcée à deux espaces.

Aussi, on utilise temporairement une version modifiée de l’extension mdformat-myst avec un script de post-traitement.

Attention

Ce site de documentation utilise encore la version standard de mdformat et mdformat-myst. On ne peut donc pas encore y utiliser les encarts marqués par :::

À discuter

Pour les listes à puces numérotées, il est possible de laisser le moteur de rendu numéroter automatiquement les puces en écrivant :

1.  bla
1.  bla bla
1.  bla bla bla

Cas particulier : lorsqu’une liste à puces s’étend sur plusieurs cellules – typiquement dans des diapos ou des exercices – la numérotation automatique dans JupyterLab-MyST reprend la numérotation à 1 dans chaque cellule ce qui n’est pas souhaitable. On peut forcer la numérotation à reprendre à une valeur ultérieure :

3.  bla
3.  bla bla
3.  bla bla bla

Souhaitons-nous forcer cette convention, notamment dans le reformatage avec mdformat?

Opinion de NT: au vu du point ci-dessus, recommander la convention, mais sans la forcer avec mdformat.

À discuter

NT: je ne suis pas convaincu par la convention de mdformat de systématiquement insérer un saut de ligne entre chaque puce, même sur des listes simples. Cela gaspille de l’espace vertical.

Typographie pour les documents en français#

Les majuscules sont accentuées.

En attendant que, comme LaTeX, MyST gère automatiquement l’affichage d’un espace fine insécable avant les :, on le fait approximativement à la main: chaque : est précédé dans les sources par un espace insécable comme dans  :. Si le clavier ne permet pas d’insérer facilement un tel espace, on se contentera d’un espace normal: : en attendant un correctif systématique par recherche et remplacement. En revanche (approximation aussi), on ne met pas d’espace avant !, ?, ;, etc.

Todo

Écriture des nombres en toutes lettres lorsque … + ref

Voir le lexique des règles typographiques en usage à l’imprimerie nationale.

Annotations de difficulté#

Un ♣ en début de phrase ou de titre indique une activité (exercice, information) pour aller plus loin qu’il n’est pas nécessaire de maîtriser pour passer à la suite.

:::{admonition} Exercice : ♣ lorem ipsum
...
:::

:::{admonition} Exercice
1.  Lorem Ipsum ...
2.  ♣ Calculez ...
:::

Textes#

  • Les textes, y compris dans les encarts comme les définitions, sont prévus pour être lus en autonomie (contrairement aux notes de cours d’Info111 ou ISD qui sont prévues comme des diapos). On utilisera donc préférentiellement des phrases complètes, des paragraphes, des mots de transition, pour donner une certaine rondeur à la lecture.

  • Le texte s’adresse au lecteur ou la lectrice à la deuxième personne, en vouvoyant en Français. On peut aussi utiliser la première personne du pluriel.

  • Le texte vise à être inclusif; autant que possible en utilisant des formulations non genrées; sinon avec écriture alternativement féminine et masculine, ou inclusive.

Terminologie#

  • Pour les terminologies techniques, on s’attache à utiliser la langue du texte. Par exemple, si le texte est en français, on minimise le franglais et les angliscimes: «renvoyer» plutôt que «retourner»; «feuille» ou «fiche» plutôt que notebook.

  • On utilise chaque fois que possible le vocabulaire du cours, comme autant d’occasions de l’ancrer dans la mémoire.

    Exemple

    «Définissez la fonction spécifiée ci-dessous» plutôt que «écrivez» ou «implantez». Variante: documentée plutôt que spécifiée si la fonction l’est par une doc.

  • Lorsque l’on parle de logiciel, de technologie, on s’attache à nommer la fonction plutôt que la marque: «faire une recherche sur internet» plutôt que «google»; «traitement de texte» plutôt que «word»; «assistant conversationnel» plutôt que «chat-GPT».

À discuter

Quel nom adopter pour une feuille Jupyter? feuille? fiche? carnet? calepin? «Calepin» est le plus sympathique, mais comme «carnet» ou «notebook» est impropre: un calepin une collection de feuilles plutôt qu’une seule.

Transitions et navigation#

Chaque feuille commence par une introduction en quelques mots décrivant ce que le lecteur va y faire et apprendre, et se termine par une conclusion similaire. La conclusion peut proposer des pistes pour aller plus loin. Cependant, sauf lorsque plusieurs feuilles forment un tout qui s’enchaîne fortement, on évite de mettre des liens vers la feuille suivante / précédente : de tels liens sont en effet rajoutés automatiquement en fonction de la façon dont les feuilles s’enchaînent dans le parcours pédagogique. Cela facilite la réorganisation d’un parcours pédagogique, et la réutilisation des feuilles entre parcours pédagogiques.

Accessibilité et portabilité#

Globalement, JupyterLab et MyST s’en sortent plutôt bien en terme d’accessibilité, dès lors que l’on mets l’accent sur le fond plutôt que sur la forme :

  • Utiliser en priorité les fonctionalités natives de Markdown/MyST (encarts, …) plutôt qu’introduire du HTML de rendu.

  • Être rigoureux sur le découpage en sections (exemple: pas de saut de # à ###)

  • Annoter systématiquement les figures avec une description alternative.

    :::{figure} bla.png
:alt: Une image d'un bla en pleine action
:::

Attention

Quel équivalent pour les knowls / hover-cards / hover-boxes sur les téléphones portables?

Code#

  • On suit les conventions PEP8.

  • Dans un document en Français, les noms de variables, fonctions, classes spécifiques au document sont en français, avec accents.

    À discuter

    Quelle convention pour les documents multilingues?

    Attention

    Mettre les accents dans le code est un choix discutable. Mais Python 3 gère très bien les accents dans le code et ailleurs, alors autant en profiter pour écrire du français correct. Il faudra juste voir si, en pratique, cela peut poser des difficultés aux apprenants pour saisir ces accents.

  • Les noms sont en une lettre lorsque cela colle avec des notations mathématiques ou physiques courantes. Sinon des mots complets, en Camel Case pour les noms de classes et minuscule séparés par des _ pour des noms de fonctions et variables.

    À discuter

    Pour les compteurs de lignes et de colonnes dans un tableau 2D: i, j? ou ligne, colonne?

  • Si pertinent, on pourra utiliser des lettres grecques et autres symboles mathématiques. Il faudra juste montrer comment les saisir interactivement avec \alpha.

Méta informations#

Notes aux enseignants#

:::{admonition} Notes aux enseignants
...
:::

Objectifs pédagogiques#

:::{admonition} Objectifs pédagogiques
Décrire les compétences qui seront travaillées. Penser implicitement: «l'étudiant est capable de ...».
:::

Choses à faire#

:::{todo} Résumé en une ligne
Description détaillée
:::

Annotations sémantiques et ontologie#

Outre les éléments narratifs ci-dessus, nous visons d’annoter tous les documents (voire à terme des fragments de ceux-ci) par des métadonnées comme suit. Cela permettra de raisonner automatiquement sur le matériel pédagogique, notamment pour faire de l’enseignement adaptatif.

---
learning:
  objectives:
    understand: expression booléenne
  prerequisite:
    apply: [variable, affectation]
---

Les clés sont: discover (activité de découverte d’une notion avant de l’avoir définie formellement), know (connaître la définition; typiquement testé par flashcard), understand (savoir reconnaître et interpréter; exercices d’application immédiate), apply (savoir utiliser). Les valeurs sont des noms de notions, ou listes de tels noms. La liste des noms de notions (à compléter!) est dans le fichier _config.yml. Ces notions incluent aussi des éléments pédagogiques comme des difficultés typiques telles que «afficher versus renvoyer». On essaye de nommer ces difficultés de façon positive (ce que l’étudiant doit comprendre): «afficher versus renvoyer» plutôt que «confusion entre afficher et renvoyer». À voir comment on traite les idées fausses (misconceptions).

À terme, on pourra envisager, dans les cas simples, de générer automatiquement une version narrative à partir de ces métadonnées. Pour le moment, et pour gagner de l’expérience, on peut aussi inclure une version narrative si certains éléments ne s’expriment pas bien sous forme de métadonnées, quitte à ce que ce soit un peu redondant.

Ces annotations s’appuient sur une ontologie, temporairement hébergée dans le fichier de configuration init-laby/book/_config.yml. Cette ontologie liste les notions définies dans le cours, avec pour chacun d’entre eux les items suivants :

  • verbalization: comment nous avons choisi de nommer la notion dans le contexte de ce cours;

  • en (optionnel): une traduction en anglais (américain);

  • mathhub (optionnel): un alignement avec l’identifiant de la notion dans l’ontologie MathHub;

  • wikidata (optionnel): un alignement avec l’identifiant de la notion dans wikidata

  • depends_on (optionnel): une autre notion qui doit être apprise avant celle-ci.

  • group (optionnel): une autre notion qui définit un groupe dont celle-ci fait partie. Par exemple, la notion «paramètre» fait partie du groupe de la notion «fonction».

Cette ontologie est actuellement utilisée pour :

  • aider les auteurs à standardiser la terminologie

  • enrichir la définition du terme dans le HTML produit avec la traduction anglaise et d’éventuels liens croisés

  • annoter le contenu avec des prérequis et objectifs d’apprentissage comme décrit ci-dessus.

À terme, elle sera utilisée pour faciliter :

  • l’assistance automatique à la traduction;

  • l’enseignement adaptatif;

  • la visualization des progrès des étudiants par notion plutôt que par activité.

Citations#

Lorsque l’on récupère ou s’inspire d’une ressource, on la cite avec le mécanisme de citation de MyST avec, autant que possible, une url pointant précisément sur le fragment réutilisé.

:::{admonition} Remerciements
Ce document est tiré de / inspiré de @...
:::

Encarts#

MyST permet de marquer des encarts (admonitions) comme dans l’exemple ci-dessus pour les remerciements. Ce sont l’équivalent des environnements en LaTeX.

Attention

L’implémentation des encarts – dans Jupyter-Book, MySTmd, JupyterLab-MyST, ou md-format-MyST – n’est pas encore uniforme et complète, notamment pour l’internationalisation et la définition d’encarts personnalisés. Une partie des conventions décrites dans cette section résulte d’un compromis pour un rendu raisonnable dans toutes les cas.

Encarts divers#

En anglais, on dispose des encarts prédéfinis hint, tip, seealso, etc. Par exemple, l’encart suivant :

:::{hint}
In English, we may use predefined admonitions such as `hint`, `tip`, ...
:::

est rendu comme suit:

Hint

In English, we may use predefined admonitions such as hint, tip, …

Certains encarts prédéfinis comme attention, danger, important, note ne nécessitent pas de traduction et peuvent donc être utilisés en Français aussi.

Dans les autres cas , on utilise une directive admonition avec un titre, et éventuellement une classe :

:::{admonition} Exemple
...
:::

Apartés, rappels, remarques, pour aller plus loin :

:::{admonition} Aparté : Lorem ipsum
:class: hint
:::

:::{admonition} Les machins en Python
:class: hint

...
:::

Astuces, indications, …

:::{admonition} Astuce
:class: tip

...
:::

Voir aussi, références, …

:::{seealso} Voir aussi
...
:::

Comment choisir la classe?

  • hint pour donner à réfléchir

  • tip pour suggérer des actions

  • seealso pour renvoyer à des information ailleurs

Lorsque l’on utilisera MyST ou JupyterBook 2, on pourra utiliser une version plus courte :

:::{hint} Aparté : Lorem ipsum
...
:::

On peut utiliser la classe dropdown pour replier l’encart par défaut; typiquement pour des indications supplémentaires à ne consulter que si l’on ne voit pas comment s’y prendre.

:::{admonition} Indication
:class: tip dropdown

...
:::

À terme, on voudra avoir une collection d’encarts nommés prédéfinis, pour pouvoir configurer leur rendu une bonne fois pour toutes, comme dans LaTeX. C’est déjà possible de définir de tels encarts avec JupyterBook et MySTmd, mais sans qu’ils soient gérés en usage interactif avec JupyterLab-Myst :

:::{apparté} Lorem ipsum
...
:::

Si un titre d’encart est donné en plus du type d’encart (comme dans ```{admonition} Astuce: Lorem ispum), le titre commence par une majuscule.

Attention

Ce point est discutable vis-à-vis des conventions typographies française qui ne mettent normalement pas de majuscules après un :. Mais cela permettra une transition facile vers des encarts nommés ````{astuce} Lorem ipsumoù la séparation entre type d'encart et titre sera assurée par autre chose qu'un:`; c’est aussi la convention qui se trouve avoir été la plus suivi dans les cours existants :-)

Définitions#

(bidule)=
:::{admonition} Définition : Bidule
Un {definiendum}`bidule` ...
:::

Le rôle definiendum indique la notion qui est définie, ainsi que le label avec lequel référencer cette notion. Si la notion et le label diffèrent (par exemple pour des questions d’accord), on peut utiliser :

Les {definiendum}`bidules <bidule>` ...

Le label peut contenir des espaces, des accents. Pour référencer la définition, on utilise un «slug» obtenu en remplaçant les lettres accentuées par les lettres non accentuées correspondantes et les espaces par des _.

Motivation

Cette annotation sémantique des définitions permet une mise en exergue systématique dans la version étudiant des carnets et la version HTML, de construire un index sur la page web, et – dans un certain nombre de cas – de faire apparaître la définition dans un hover card quand on passe la souris sur un lien vers la notion.

À terme elle permettra de générer des flashcards pour des révisions, facilitera l’enseignement adaptatif, etc. Voir aussi Ontologie et annotations sémantique.

Todo

Implanter le rôle definiendum sur py-edu-fr.

Définitions avec encarts Syntaxe et Sémantique:

::::{admonition} Définition: Foo

Lorem ipsum dolor ...

:::{admonition} Syntaxe
...
:::

:::{admonition} Sémantique
...
:::
::::

Todo

Tableaux résumés de listes d’opérations?

Exercices#

En anglais, on peut utiliser les encarts standards pour les exercices, ainsi que leurs variantes pouvant porter sur plusieurs cellules.

Ces encarts ne sont pas encore internationalisés. Du coup, en Français, on utilise un encart manuel Exercice.

Chaque action est un item d’un enumerate. On utilise l’impératif.

:::{admonition} Exercice

1.  Faites blah blah blah
2.  Exécutez blah blah bla

:::

Il est bon de mettre un titre à l’exercice, et de numéroter les exercices dans une feuille (en attendant que ce soit fait automatiquement).

:::{admonition} Exercice 3 : lorem ipsum
...
:::

MyST dans un carnet Jupyter ne permet pas (encore) de réaliser des encarts manuels sur plusieurs cellules. Ce serait pourtant bien utile pour pouvoir, par exemple, inclure des cellules de code dans un exercice, ou pour faire des diapos où le contenu de l’encart apparaît en plusieurs itérations. Pour le moment, on utilise en Français l’approximation suivante :

:::{admonition} Exercice
...
:::

puis dans les cellules de texte suivantes:

:::{admonition} Exercice (suite)
...
:::


```{attention}
Une «admonition» sans contenu est un abus de la syntaxe MyST; tous les
outils ne la gère pas bien. On essaye d'éviter quand on peut.

Solutions; version étudiant versus version instructeur#

Les documents rédigés ici sont à destination des instructeurs. La version distribuée aux étudiants est généré automatiquement grâce aux conventions décrites brièvement ci-dessous, en supprimant les notes aux enseignants, les solutions, en verrouillant certaines cellules, etc. Pour cela on utilise travo-prepare qui suit et étends les conventions de nbgrader (à discuter et configurer pour py-edu-fr).

De même, sur la page web, les notes aux enseignants, les todos, et les solutions peuvent être cachées par défaut, ou supprimées (à discuter et configurer pour py-edu-fr).

Solutions#

Pour délimiter une solution de référence, notamment pour produire des textes ou codes à trous (multiples) que l’étudiant.e doit compléter, on insère une ligne contenant le marqueur BEGIN SOLUTION (resp. END SOLUTION) pour indiquer le début (resp. la fin) de la solution.

def factorielle(n):
    if n == 0:
        ### BEGIN SOLUTION
        return 1
        ### END SOLUTION
    else:
        ### BEGIN SOLUTION
        return n * factorielle(n-1)
        ### END SOLUTION

Les lignes avec les marqueurs de début et de fin doivent être indentées de façon identique et cohérente avec le contexte.

Pour des réponses dans les cellules markdown, on mets des sauts de ligne avant et après les marqueurs pour un meilleur rendu :

1.  Décrivez bla bla bla

    BEGIN SOLUTION

    bla bla bla

    END SOLUTION

Pour des solutions que l’on souhaite inclure dans la feuille de l’étudiant, on pourra utiliser alternativement un encart «Solution», replié ou pas par défaut :

:::{admonition} Solution
:class: dropdown

...
:::

À terme, lorsque JupyterLab-MyST donnera un rendu satisfaisant, on pourra utiliser l’encart standard :

:::{solution}
...
:::

Métadonnées de cellule; correction et rétroaction automatique#

Pour chaque cellule, on peut définir (dans l’onglet Create Assignment de la barre de droite) un type : lecture seule, cellule autocorrigée, cellule de test. Pour ces dernières, on peut associer des points: si la cellule s’exécute sans exception, l’étudiant reçoit les points indiqués, sinon non. (cf dépôt de cours info 111).

Alternativement, on peut utiliser des tags, ce qui donne des métadonnées plus concises. Voir la documentation de prepare pour les détails.

Exercices Jupylates#

Voir la documentation de Jupylates.