Traduire de la documentation à l'école

[vpoulailleau]

Bonjour à tous,

Comme évoqué lors de la PyConFr, je suis entre autres enseignant de Python de bac+1 à bac+5. J'ai évoqué à l'équipe de direction de deux écoles la possibilité d'animer des ateliers d'initiation aux logiciels libres sans être expert en programmation, le tout en participant à la traduction de la doc Python.

Leur réponse est :

[…] excellente idée que cet atelier. Je (nous) sommes preneur ! Et oui pour que tu l’animes : un sachant qui les accompagne dans leur initiation au monde du libre et du travail collaboratif me semble indispensable.

Nous n'avons pas encore établi les modalités, mais je me pose des questions quant à l'organisation :

• Est-ce que chaque étudiant doit réserver un fichier différent ? Ou peut-on se mettre d'accord au sein du groupe pour ne pas se marcher sur les pieds au sein d'un seul et même fichier (et j'imagine alors une seule issue) ?
• Préférez-vous recevoir directement toutes les pull requests ? Ou dois-je les faire travailler sur mon fork pour centraliser les pull requests (ceci dit, je ne sais pas comment est alors gérée l'attribution, l'accord de contribution à la documentation) ?
• J'imagine qu'il est préférable que je fasse le maximum de review en « temps réel », non ?
• Avez-vous eu connaissance de personnes qui ont organisé des choses similaires avec des étudiants ? Quels ont été les retours d'expérience ?

Et si vous avez des remarques complémentaires, n'hésitez pas !

[Seluj78]

Hello @vpoulailleau !

Bonjour à tous,

Comme évoqué lors de la PyConFr, je suis entre autres enseignant de Python de bac+1 à bac+5. J'ai évoqué à l'équipe de direction de deux écoles la possibilité d'animer des ateliers d'initiation aux logiciels libres sans être expert en programmation, le tout en participant à la traduction de la doc Python.

Leur réponse est :

[…] excellente idée que cet atelier. Je (nous) sommes preneur ! Et oui pour que tu l’animes : un sachant qui les accompagne dans leur initiation au monde du libre et du travail collaboratif me semble indispensable.

Je suis ravi d'entendre ca !

Nous n'avons pas encore établi les modalités, mais je me pose des questions quant à l'organisation :

* Est-ce que chaque étudiant doit réserver un fichier différent ? Ou peut-on se mettre d'accord au sein du groupe pour ne pas se marcher sur les pieds au sein d'un seul et même fichier (et j'imagine alors une seule _issue_) ?

Non je pense que a moins que ils soient plusieurs derrière un ordinateur sur un seul fichier, il faut une reservation (et donc issue) et donc fichier par étudiant/groupe d'étudiant

* Préférez-vous recevoir directement toutes les pull requests ? Ou dois-je les faire travailler sur mon fork pour centraliser les pull requests (ceci dit, je ne sais pas comment est alors gérée l'attribution, l'accord de contribution à la documentation) ?

Je vote pour que on les recoive toutes ici, je pense que c'est beaucoup plus simple !

* J'imagine qu'il est préférable que je fasse le maximum de review en « temps réel », non ?

Oui, avant de faire la PR mais apres 🤷‍♂

* Avez-vous eu connaissance de personnes qui ont organisé des choses similaires avec des étudiants ? Quels ont été les retours d'expérience ?

Pas de mon coté, désolé !

Et si vous avez des remarques complémentaires, n'hésitez pas !

il ne faudra pas oublier de leur dire de revenir sur github repondre et corriger nos suggestions etc...

A part ca, c'est une super idée et je suis impatient de relire leur PR !!!!

[vpoulailleau]

Merci pour tes conseils !

Pour le coup de la relecture de PR, je me demande quand même si je ne dois pas relire après qu'ils aient fait la PR (genre aussitôt qu'ils ont fait la PR) : cela leur apprend le mécanisme de prise en compte des remarques, afin de les rendre autonomes. En plus ils peuvent me poser les questions de vive voix tout en pratiquant en conditions « réelles ». Qu'en penses-tu ? Et si tout le monde est d'accord, il pourrait être envisagé de mettre un commentaire de pull request du style « en attente de review de @vpoulailleau » pour éviter de vous surcharger de travail avant que le niveau de qualité raisonnable soit atteint.

Et puis, je ferai un peu de pub pour https://github.com/vpoulailleau/padpo ;-) Ça devrait aider à éviter certaines erreurs.

[JulienPalard]

je me demande quand même si je ne dois pas relire après qu'ils aient fait la PR

Tu peux bien sûr relire, on autorise bien sûr tout le monde à relire, ça ne fait donc pas exception "pour l'école", on suit "un processus de contribution habituel" avec des gens qui font des PR et d'autres qui les relisent, commit bit ou pas.

On apprécira que tu relise d'ailleurs, c'est du boulot la relecture. Tu peux aussi proposer à des élèves de relire les PR des autres.

en attente de review de @vpoulailleau

On verra si c'est ingérable on fera quelque chose du genre, pour le moment je ne pense pas que ce soit nécessaire.

Et puis, je ferai un peu de pub pour https://github.com/vpoulailleau/padpo ;-) Ça devrait aider à éviter certaines erreurs.

Hop je vais voir ça.

[vpoulailleau]

On apprécira que tu relise d'ailleurs, c'est du boulot la relecture. Tu peux aussi proposer à des élèves de relire les PR des autres.

Bonne idée !

Merci aussi pour tes conseils !

[JulienPalard]

Pour padpo, pas de pot on a beaucoup d'erreur dues aux tags restructuredText. Ça me rappelle que ... j'avais déjà essayé et abandonné à cause de ça.

J'avais tenté de remplacer les tags par des mots "bien choisis" pour plaire à grammalecte mais sans succès. pospell fonctionne en tronquant très violement tout les tags rst, rendant quelque chose de très faux gramaticalement, comme :

par et avec . Disponible à l'adresse . Ce livre est un classique en informatique. Les chapitres 2 et 3 présentent l'utilisation des séquences et des flux pour organiser le flot de données dans un programme. Les exemples du livre utilisent le langage mais la plupart des approches décrites dans ces chapitres s'appliquent au style fonctionnel de .

mais qui plaît à hunspell.

[vpoulailleau]

Pour padpo, pas de pot on a beaucoup d'erreur dues aux tags restructuredText.

Bon, j'avoue je ne l'ai pas testé à fond 😛

Ceci dit, sur la page que j'ai vérifiée, je n'ai pas eu de problème de tag rst vu que ce sont les tags que j'ai fait gérer (suffisamment pour cette page) à padpo ! D'ailleurs tu es marqué comme pending reviewer sur ces corrections dans la #978 😉

Mais effectivement, il faudrait ajouter tous les tags rst à padpo. Ce genre d'atelier avec les étudiants peut me confronter aux limites de padpo, et me fournir des idées d'amélioration.

[JulienPalard]

On pourrait aussi faire tourner gramalecte sur la sortie texte de Sphinx, plus simple non ?

[vpoulailleau]

On pourrait aussi faire tourner gramalecte sur la sortie texte de Sphinx, plus simple non ?

Plus simple, je ne suis pas complètement convaincu (d'un point de vue utilisateur, pas développeur d'outil). Mais ceci dit, deux vérifications valent mieux qu'une ! Est-ce qu'un passage de grammalecte sur la doc générée pourrait/devrait être ajouté au makefile ? Genre message d'information.

[vpoulailleau]

Je clos cette issue, merci pour toutes vos réponses. Je vous tiens au jus des avancées du projet. Je vois bientôt l'équipe pédagogique pour discuter des modalités de·s· atelier·s· au retour du congés de certaines personnes.

[vpoulailleau]

J'ai mis le support de présentation que je compte utiliser pendant l'atelier de traduction ici : https://github.com/vpoulailleau/support-traduction-doc-python

Vous pouvez faire vos remarques, si vous le souhaitez, en créant un ticket dans le repo mentionné.

Vous pouvez aussi réutiliser ce document pendant des ateliers.