Homogénéisation du syllabus: création de conventions

[francoismichel]

Bonjour à tous,

Après avoir discuté avec Alexandre et Olivier Goletti, nous pensons que la prochaine étape pour ce syllabus est d'homogénéiser son contenu. On vous propose donc d'établir des conventions d'écriture que l'on respectera ensuite lors de l'écriture d'une page. On a déjà réfléchi à une base, mais n'hésitez pas à donner votre avis et à proposer de nouvelles idées.

Mise en forme du texte

Par rapport à la mise en forme du texte, sans parler du contenu, on pense à ceci :

• Utilisation de l'italique uniquement pour des mots en langue étrangère (typiquement l'anglais ici).
• Utilisation du gras pour un terme "technique" (par exemple: variable, portée lexicale, ...) utilisé pour la première fois
• Utilisation du pré-formattage (i.e. morceau de code) pour tout mot-clés de Java (e.g String, + , - , for , ...) ou tout "petit bout de code" (e.g a = 2) , des exemples de nom de variables, une signature de fonction, ...)
• Lorsque vous devez insérer du code, pensez à utiliser une directive .. code-block:: java qui donnera de la coloration syntaxique. On vous propose maintenant aussi d'insérer votre code dans une tâche spéciale prévue à cet effet (nommée execute_java, voir https://github.com/OpenWeek/java-syllabus-pages/tree/master/cours_inginious/tutorial/execute_java) qui affiche un texte éditable et permet à l'étudiant d'exécuter le code: la tâche affichera ce qui aura été écrit sur stdout. Je pense qu'on peut déjà rtès facilement prendre un bon nombre d'exemples qui ont été donnés dans le syllabus et les insérer dans cette tâche (remplacer .. code-block:: java par .. inginious:: execute_java, et s'assurer que le code écrit des choses intéressantes sur stdout qui illustrent bien ce que le bout de code fait). N'utilisez ces éléments que pour du Java pour éviter les confusions. Si vous devez inclure du code d'un autre langage, utilisez une image ou un autre format
• Utilisation de guillemet uniquement pour les citations, suivis de la référence
• Utilisation de la même indentation pour tous les codes Java. On vous propose "un niveau d'indentation = 4 espaces" ?
• Pour tout le reste, utilisation une police normale

Pédagogie

Quelques idées d'un point de vue pédagogique maintenant:

• Lorsqu'un mot est mis en gras, il doit être défini de manière précise en prenant en compte les connaissances de l'étudiant. Donc par exemple, le concept de classe ne pourra pas être défini de manière complète dès la première page. Une fois que la notion a été vue, dans les quelques chapitres qui suivent (jusqu'à ce que le concept soit bien assimilé par l'étudiant), si l'on réutilise le concept, redonner la définition via un hyperlien ou un tooltip.
• Quand c'est possible, mettre après la définition d'un nouveau terme technique, un court exercice ou exemple exécutable (via la tâche execute_java par exemple) qui permet au lecteur de bien l'apréhender. Par exemple pour le concept d'assignations, il est facile de faire un petit exercice/exemple exécutable pour bien faire comprendre le concept. La première fois qu'on rencontre le concept de classe, ce n'est pas la partie qui nous intéresse donc ce n'est pas utile de faire un exercice.
• Lorsque l'on présente un exemple de code Java, mettre des commentaires. Ces commentaires doivent être le plus générique possible. Par exemple, sur cette page, on voit que l'auteur identifie les sous-étapes du code, et les traduit en langage naturel dans les commentaires. On peut par contre se passer de commentaires qui traduisent uniquement une ligne de code, du genre // j'assigne la variable i à la valeur 4
• Tous les bouts de codes présentés dans le syllabus doivent être exécutables par l'utilisateur (soit en utilisant une directive de code utilisable, soit l'utilisateur peut reprendre le code tel quel et le compiler puis le lancer).
• Ne pas utiliser de pseudo-code: il est intéressant de privilégier du code syntaxiquement valide. On peut donc remplacer le pseudo code par un System.out.println("Telle action est effectuée") ou un appel de fonction effectuer_telle_action(). Utiliser des print permettra d'utiliser facilement la tâche execute_java
• Par rapport à la structure d'un chapitre. Commencer le chapitre par un exemple, expliqué en français qui justifierait l'intérêt ed la notion que l'on va voir. Exemple pour les boucles for: On aimerait savoir si un nombre est premier, calculer son nombre de diviseurs, afficher un message toutes les cinq minutes pendant 3 heures, .... Ensuite, au fil de la théorie, donner le code qui résoudrait l'exemple et quelques petits exercices. Par exemple, on veut expliquer les boucles. On explique une situation de tous les jours où l'on aimerait trouver l'étudiant qui a la meilleure note de la classe, on explique en français comment devrait se comporter l'algorithme. Ensuite, au fur et à mesure que l'on avance dans la théorie, on construit petit à petit l'algorithme en Java. On pourrait aussi rajouter de petits exercices pour aider à la compréhension de la matière.

Création d'une page

Comme le projet est Open-Source, n'importe qui peut avoir envie d'écrire une page à n'importe quel moment et plusieurs personnes peuvent travailler ensemble sur une page/chapitre, il est donc important de se coordonner. Il serait donc intéressant d'avoir une marche à suivre pour travailler ensemble facilement sur l'élaboration d'une page par étapes. Les différentes étapes que l'on pourrait suivre seraient :

1. Définir le sujet du chapitre
2. Définir l'ensemble des choses dont nous allons discuter dans le chapitre (par exemple, dans le chapitre sur les boucles on peut volontairement laisser de côté les for-each
3. Établir l'ensemble des pré-requis pour le chapitre. Il est possible de ré-aborder certains concepts par après. Par exemple, une fois qu’on a fait les conditions simples, reparler des expressions que l'on évalue dans le cadre d’une condition.
4. Définir l'ordre dans lequel les éléments théoriques vont être proposés
5. Écrire une page minimaliste uniquement avec la théorie
6. Une fois que le contenu théorique est satisfaisant, l'enrober d'exemples et d'exercice
7. Citer les éventuelles sources d'inspirations/traduction (Notamment le syllabus de Java du cours de bac1 pour ceux ayant traduit des parties)

Voilà ce qui est ressorti de nos discussions. Qu'en pensez-vous ? Certains points sont plus prioritaires que d'autres (exemple, il est plus important d'avoir rapidement une forme homogène pour le syllabus que d'avoir un tooltip ou un hyperlien pour chaque nouvelle notion vue), mais tous ont un intérêt.

Ce ne sont que des propositions, on attend donc vos avis et n'hésitez pas à faire vos propres propositions !

Encore un grand merci à tous,

Alexandre & François

[AlexandreDubray]

Quelques idées supplémentaires qui pourraient être intéressante (reprise notamment d'erreurs courantes trouvées par Olivier Goletti)

• Faire un chapitre sur la compilation et l'exécution d'un code java (via terminal, IDE, etc) avec une section du type "comprendre la sortie du compilateur". On en profiterait pour expliquer les étapes entre ce que la personne écrit et ce qui est vu par l'ordinateur de manière simple et intuitive (pas besoin de détailler le fonctionnement de la JVM). On peut aussi rajouter une partie sur les exceptions les plus fréquentes (ArrayOutOfBound, NullPointer, etc).
• Comment trouver de l'aide sur internet et où trouver les ressources dont on a besoin pour écrire du code (API Java par exemple)
• Comment tester son code
• Faire un dépot avec l'ensemble des codes (complet et exécutable) du syllabus pour rediriger les étudiants vers

[ogoletti]

Comment propose-t-on de citer le cours dont sont traduits certaines pages ? Directement dans le texte ? Ou simplement dans les sources de la page ?

[francoismichel]

Je propose dans un premier temps d'ajouter un bandeau en italique au début des pages concernées

[ogoletti]

Pour info, il y a une clause NC sur http://math.hws.edu/javanotes/. Et donc SA nous oblige de mettre NC sur les parties du syllabus qui sont traduites.

[mpiraux]

Une convention sur le placement des accolades devrait être aussi adoptée.