Vous pouvez faire un don au Programming Historian

Consignes aux rédacteurs et aux rédactrices

Cette page fournit des instructions détaillées aux rédacteurs et rédactrices qui apportent leur concours lors de l’évaluation par les pairs dans le cadre du Programming Historian en français.

Le rôle du rédacteur et de la rédactrice

Nous vous remercions d’assurer le travail éditorial pour une leçon du Programming Historian en français, nous vous savons gré pour vos efforts. Ce guide a comme objectif de garantir la cohérence et la qualité de la collaboration entre auteur(e)s, rédacteurs/rédactrices et évaluateurs/évaluatrices avec le Programming Historian en français. Pour toute question qui porte sur les consignes, merci de contacter par courriel un des membres du conseil éditorial ou de poser une question sur notre espace dédié sur Github. Merci de le faire aussi si vous jugez que ces consignes doivent être améliorées ou mises à jour.

Contenus

Qu’il s’agisse du suivi éditorial d’une leçon originale ou d’une traduction, notre rôle n’est pas celui d’un gardien, comme dans les revues traditionnelles, mais d’apporter notre concours lors du processus d’écriture, de traduction, d’évaluation et de publication. Merci donc de prendre connaissance de nos consignes de rédaction et de traduction. Nous encourageons toujours les personnes susceptibles de rédiger une leçon de soumettre un plan détaillé de leurs idées avant d’entamer l’écriture. Si néanmoins un texte ne convient pas au Programming Historian en français, il nous incombe de le dire avant que l’auteur(e) ne s’avance trop dans la rédaction d’un tutoriel. Ainsi, nous espérons que cela évite à toutes et à tous de perdre du temps et de l’énergie. Une fois les discussions avec un(e) auteur(e) entamées et son idée encouragée, nous fournissons par la suite un soutien constant jusqu’à la publication de la leçon.

Un espace d’échange sûr

Le Programming Historian en français s’engage à fournir un espace sûr pour l’échange d’idées où personne n’aura peur de se faire harceler ou attaquer. Le rédacteur ou la rédactrice a un rôle fondamental pour le maintien de telles conditions car une de vos missions est de constamment renforcer notre politique contre le harcèlement. Si vous avez besoin d’aide, merci de vous adresser au reste du comité éditorial ou notre médiatrice Hélène Huet. Vous pouvez vous renseigner davantage sur notre engagement pour des espaces d’échange sûrs sur le blog du projet.

Politique contre le harcèlement

Vous trouverez ci-dessous les principes du Programming Historian en français qui doivent inspirer les échanges entre évaluateurs et évaluatrices, auteur(e)s, rédacteurs et rédactrices, ainsi que toute personne contribuant à nos forums publics.

Le Programming Historian en français tient à garantir un environnement académique ouvert à la communauté, qui offre la pleine liberté d’explorer minutieusement des idées, poser des questions, faire des suggestions ou demander des clarifications. Il fournit aussi un espace libre de toute discrimination envers les personnes contribuant au projet, indépendamment du genre, de l’orientation sexuelle, des situations d’handicap, de l’apparence physique, de la masse corporelle, de l’origine, de l’âge, de la religion ou de l’expérience technique. Nous ne tolérons aucune forme de harcèlement ou d’attaque personnelle contre les membres de la communauté. Les personnes qui violent ces règles sont susceptibles d’être expulsées de la communauté à la discrétion du conseil éditorial. Toute personne en mesure de témoigner de tels comportements ou qui en est la victime peut contacter notre médiatrice Hélène Huet. Merci de nous aider à créer un espace d’échange et de discussion sûr.

Suivi des leçons proposées

Lorsqu’une proposition de leçon reçoit le feu vert par l’équipe éditoriale, un rédacteur ou une rédactrice lui est assigné(e) pour mener un travail en commun avec l’auteur(e) dans le but de définir des objectifs clairs pour la leçon et de fixer un délai de publication. Habituellement, nous recommandons de respecter un délai de 90 jours à partir du moment où les discussions sont entamées, mais ce délai peut être réajusté si nécessaire.

Le rédacteur ou la rédactrice doit alors créer un nouveau ticket intitulé “Proposition de leçon” dans le dépôt des soumissions sur Github en le signalant avec l’étiquette “proposal”. Le texte par défaut à utiliser comme introduction se trouve dans le gabarit du ticket ou alors il peut être copié ci-dessous.

Le Programming Historian en français a reçu la proposition suivante d'une leçon intitulée 'TITRE PROVISOIRE DE LA LEÇON' de la part de NOM(S) D'AUTEUR(E-S). Les principaux objectifs pédagogiques envisagés sont:

- principal objectif pédagogique no 1
- principal objectif pédagogique no 2
- principal objectif pédagogique no 3 (ajouter plus si besoin)

Pour s'assurer d'une rapide publication sur ce sujet d'importance, nous nous sommes mis d'accord sur une date de dépôt qui ne dépasse pas [90 JOURS PAR DÉFAUT OU PLUS SI AGRÉÉ PAR LE(LA) REDACTEUR(TRICE)]. Les auteur(e)s sont d'accord pour contacter le(la) rédacteur(trice) en avance s'ils ont besoin de revoir le délai.

Si la leçon n'est pas déposée d'ici le [DATE AGRÉÉE], le rédacteur ou la rédactrice tentera de contacter les auteur(e)s. Sans mise à jour de leur part, ce ticket sera clos, il peut toutefois être à nouveau ouvert sur demande des auteur(e)s.

Le principal contact éditorial pour cette leçon est [NOM D'UTILISATEUR/UTILISATRICE DU RÉDACTEUR/DE LA RÉDACTRICE]. Pour tout souci, les auteur(e)s peuvent contacter notre médiatrice Hélène Huet.

Le rédacteur ou la rédactrice peut adapter le texte du ticket de proposition en fonction d’éventuels objectifs supplémentaires ou de prérequis agréés avec l’auteur(e) ou les auteur(e)s.

Lorsque les fichiers de la leçon (texte et, le cas échéant, images et données) sont prêts à être soumis, l’auteur(e) contacte le rédacteur ou la rédactrice assigné(e) qui les téléversera dans notre dépôt dédié à l’évaluation par les pairs sur Github, après avoir vérifié la qualité des métadonnées.

  1. Téléverser la leçon (ou la traduction): le fichier de la leçon doit être téléversé dans le sous-répertoire des leçons; s’il s’agit d’une traduction, le fichier est téléversé dans le sous-répertoire des traductions. Si vous avez besoin d’aide, merci de consulter la documentation de Github.
  2. Téléverser des images: si des images accompagnent la leçon (ou la traduction), assurez-vous que le nommage des fichiers est conforme aux règles spécifiées dans les consignes aux auteur(e)s. C’est au rédacteur ou à la rédactrice - vous!- de créer un sous-répertoire spécifique aux images de la leçon dans le répertoire des images. Ce sous-répertoire doit être nommé exactement de la même manière que le fichier de la leçon. Téléversez ensuite les fichiers images dans ce sous-répertoire.
  3. Téléverser des données: si la leçon est accompagnée de fichiers de données, ces fichiers doivent être téléversés dans un sous-répertoire créé dans le répertoire assets et nommé exactement de la même manière que le fichier de la leçon.

Après le téléversement, le rédacteur ou la rédactrice assigné(e) doit vérifier l’historique des contributions (commits) au dépôt pour vérifier que le téléversement a bien réussi. Si ce n’est pas le cas, merci de consulter le wiki pour détecter l’erreur et résoudre le problème. Lorsque la soumission de la leçon (ou de la traduction) aura été achevée, le rédacteur ou la rédactrice assigné(e) crée un ticket d’évaluation en fermant celui de la proposition. À partir de cette étape, votre rôle implique aussi de veiller à ce que l’auteur(e) (ou le traducteur) travaille sur cette version de la leçon (ou de la traduction) et contribue directement ses modifications au dépôt Github.

Évaluation ouverte par les pairs

Le Programming Historian en français pratique l’évaluation ouverte par les pairs. Si notre conviction est bien que ce système garantit la qualité des rapports et le partage productif des idées, les auteurs ont toutefois le droit, que nous devons respecter, de solliciter une procédure fermée d’évaluation par les pairs. Une personne peut être réservée vis-à-vis d’une évaluation ouverte pour plusieurs raisons et, de notre côté, nous encourageons les auteur(e)s à choisir l’option qui leur convient le mieux.

Avant de solliciter des évaluations externes, le rédacteur ou la rédactrice doit lire et tester le tutoriel, en profitant de l’expérience acquise dans le cadre du Programming Historian en français pour aider l’auteur(e) à apporter des améliorations, si nécessaire. Le rédacteur ou la rédactrice passe au crible le caractère durable du dépôt pour vérifier si les versions des logiciels et des dépendances sont clairement mentionnées, mais aussi que les exigences spécifiques du logiciel, tout comme les captures d’écran se limitent à ce qui est nécessaire pour compléter la leçon. Il/elle veille, enfin, à ce que la leçon mobilise la documentation des logiciels lorsque celle-ci est disponible et pertinente. Les rédacteurs et rédactrices doivent aussi s’assurer que les leçons s’abstiennent autant que possible de fournir des instructions spécifiques comme “faire un clic droit sur l’icône x pour accéder au menu x,” et qu’ils offrent, en revanche, des aperçus méthodologiques plus larges. La liste de vérification éditoriale offre plus de détails sur les pratiques de pérennisation pour le PH.

Souvent, les rédacteurs et les rédactrices doivent apporter leur concours pour identifier les publics ciblés par une leçon, ou encore pour décrypter un jargon technique qui nécessite d’être clarifié. Cette relecture initiale permet aux évaluateurs et évaluatrices externes de se concentrer à l’amélioration du reste de la leçon. D’habitude, cela se fait de manière transparente dans le cadre de notre système de soumissions (voir ci-dessous), mais l’évaluation peut aussi être privée sur demande des parties intéressées.

Lorsqu’un(e) auteur(e) a revisé le tutoriel de manière satisfaisante, c’est au rédacteur ou à la rédactrice de faire formellement appel à deux personnes pour lancer l’évaluation par les pairs. Certes, le choix lui appartient entièrement, cependant, en ce sens que nous devons respecter notre engagement en faveur de la diversité, nous espérons qu’aucun effort n’aura été épargné pour que les personnes choisies aient des profiles diversifiés en termes de genre, de nationalité, de culture, d’âge ou d’appartenance académique. Merci donc de faire de votre mieux pour ne pas trouver deux personnes qui vous ressemblent trop.

Nos demandes d’évaluations sont organisées à l’aide d’un tableur Google intitulé “Programming Historian - Reviewer Tracking” que nous vous prions de bien vouloir utiliser (vous pouvez contacter le rédacteur ou la rédactrice en chef ou Jeri Wieringa si vous avez besoin d’aide pour accéder au tableur). Avant de proposer une évaluation, merci de vérifier si la personne sollicitée n’a pas été récemment contactée par un autre membre de l’équipe de rédaction. Pour éviter de surcharger les évaluateurs et évaluatrices, merci de limiter vos demandes à une par an. Si une personne a été sollicitée dans l’année passée, le champ “date_contacted” apparaitra en rouge.

Pour chaque personne pressentie en tant qu’évaluateur ou évaluatrice, indépendamment de la réponse, merci d’insérer:

Pour les dates, merci d’utiliser le format mm/jj/aaaa.

Lorsque la proposition est faite aux candidat(e)s, le rédacteur ou la rédactrice doit mettre à leur disposition nos consignes aux évaluateurs et évaluatrices et fixer le délai pour compléter l’évaluation (habituellement un mois) pour que le tutoriel puisse être publié à temps.

Quand une leçon est soumise, le rédacteur ou la rédactrice doit ouvrir un nouveau ticket sur notre dépôt de soumissions sur Github. C’est là que va se passer l’évaluation ouverte, puisque des messages qui peuvent être postés via l’interface permettent à tout un chacun de suivre la discussion. Pour cela, il est nécessaire pour toutes les parties prenantes d’avoir un compte Github gratuit.

Le commentaire initial

Votre premier commentaire sur le ticket d’évaluation d’un tutoriel doit être calqué sur le modèle de celui qui explique le rôle du rédacteur et de la rédactrice, décrit la procédure de l’évaluation ainsi que les options qui se présentent au cas improbable où des problèmes surgiraient. Merci d’adapter le modèle, qui devrait apparaître automatiquement lors de l’ouverture d’un nouveau ticket, de la manière qui correspond:

Le Programming Historian en français a reçu la leçon (ou la traduction de la leçon) intitulée '[TITRE DE LA LEÇON]' par [NOM D'UTILISATEUR/UTILISATRICE GITHUB DE L'AUTEUR(E)] ou, s'il s'agit d'une traduction, traduite par [NOM D'UTILISATEUR/UTILISATRICE GITHUB DU TRADUCTEUR OU DE LA TRADUCTRICE]). La leçon (ou la traduction) est actuellement en cours d'évaluation et peut être consultée ici:

http://programminghistorian.github.io/ph-submissions/fr/en-cours/["originales"ou "traductions"/[NOM-DE-FICHIER-ICI]

J'exercerai le rôle de rédacteur/rédactrice lors de la procédure de l'évaluation. Cela implique de solliciter deux évaluations par la communauté et de gérer les discussions qui auront lieu sur ce forum. J'ai déjà fait une lecture critique de la leçon puis un retour auquel l'auteur(e) a répondu.

Les membres de la communauté plus large sont aussi invités de fournir une critique constructive via ce fil de messages, après avoir pris connaissance de nos consignes aux évaluateurs et évaluatrices (/fr/consignes-evaluateurs) et accepté notre politique contre le harcèlement (cf. ci-dessous). Nous demandons que toute nouvelle évaluation cesse après que la seconde, parmi celles qui ont été formellement sollicitées, a été déposée, pour que l'auteur(e) puisse se concentrer sur les révisions à faire. Lorsque cela est le cas, je prendrai soin de l'indiquer dans le fil de discussion.

Je vais essayer de garder la discussion ouverte ici sur Github. Si quelqu'un a besoin de discuter en privé, merci de m'envoyer un courriel. Il y a toujours la possibilité de vous adresser à notre dispositif de médiation, si vous le souhaitez.

Politique contre le harcèlement.
_

Ceci est une déclaration des principes du Programming Historian en français et définit nos attentes concernant le ton et le style des échanges entre évaluateurs/évaluatrices, auteur(e)s, rédacteurs/rédactrices et toute autre personne contribuant à nos forums publics. Le Programming Historian en

Le _Programming Historian en français_ a pour but d'offrir un environnement académique ouvert, qui permet aux membres de la communauté de se sentir libres d'examiner des idées en détail, de poser des questions, de faire des suggestions, ou de formuler des demandes de clarification. Nous insistons sur l'importance de faire en sorte que cet espace de discussion reste respectueux et exempt de tout harcèlement pour tous les contributeur(trice)s, quels que soient leur genre, leur identité et leur expression de genre, leur orientation sexuelle, leur handicap, leur apparence physique, leur masse corporelle, leurs origines, leur âge, leur religion, ou leur expérience technique. Nous ne tolérons pas, sous quelque forme que ce soit, le harcèlement ou les attaques ad hominem contre les membres de la communauté. Les participant(e)s qui violeraient ces règles pourront être exclu(e)s de la communauté à la discrétion du comité éditorial. Si quelqu'un est témoin ou pense avoir été victime des agissements décrits plus haut, veuillez prendre contact avec notre médiatrice [Hélène Huet](/fr/equipe-projet). Merci de nous aider à créer un espace de discussion et d'échange sûr.

Mener la discussion

Votre rôle de rédacteur ou de rédactrice signifie que les personnes impliquées dans les différentes étapes de la procédure vont s’appuyer sur vous pour s’orienter. Pour la plupart des auteur(e)s et des évaluateurs/évaluatrices, il peut s’agir d’une première expérience de notre dispositif d’évaluation par les pairs. La publication immédiate des expertises sous forme de commentaires dans le ticket correspondant signifie que les auteur(e)s peuvent en prendre connaissance avant vous. C’est pourquoi il vous incombe d’indiquer clairement les étapes de la procédure et préciser quand chaque personne doit participer ou attendre des instructions complémentaires.

Il vaut toujours mieux définir des étapes clés dès que possible. Par exemple, à la suite de la réception de la première évaluation, publiez un message en remerciant l’évaluateur ou l’évaluatrice et en faisant savoir à l’auteur(e) qu’une expertise supplémentaire est attendue. À cette occasion, n’hésitez pas à lui suggérer d’attendre que la seconde expertise arrive avant de répondre. De cette manière, toutes les personnes savent à quoi s’attendre.

Si vous n’êtes vraiment pas disponible, faites si possible un bref message expliquant que vous êtes au courant des activités en cours, mais que vous avez besoin de plus de temps pour répondre de manière correcte. Satisfaire les attentes des personnes impliquées est élémentaire pour que tout le monde soit heureux.

Résumer les points principaux de l’expertise

Une fois que les deux évaluations formelles sont prêtes, de même que toute contribution en provenance de la communauté, vous devez faire un résumé des suggestions faites et indiquer clairement à l’auteur(e) les modifications qui lui sont proposées. Si certaines propositions ne correspondent pas à l’esprit du Programming Historian en français, il faut indiquer à l’auteur(e) de ne pas en tenir compte. Merci de vous mettre à la place d’un(e) auteur(e) qui reçoit une évaluation: la personne a besoin d’indications claires, tout en maintenant la liberté de rejeter parmi les suggestions qui lui sont faites celles qui n’améliorent pas nécessairement son écrit. La personne doit encore avoir le sentiment que les objectifs sont bien fixés. Un bon résumé des expertises offre à l’auteur(e) la possibilité de réagir tout en garantissant la publication de son travail, si les principaux obstacles sont dépassés.

Gérer la procédure de la révision

Lorsque vous fournissez le résumé des expertises et les instructions finales à l’auteur(e), rappelez aussi le délai de quatre semaines accordé pour faire les révisions. Fixer un délai garantit un horizon de publication des leçons et évite une prolongation de la procédure sans raison. Si l’auteur(e) a du mal à respecter le délai, il lui incombe de contacter le rédacteur ou la rédactrice pour convenir d’une date appropriée.

Questions techniques de l’évaluation - liste de vérification éditoriale

Notre procédure d’évaluation par les pairs est menée sur notre dépôt des soumissions sur Github. Des instructions détaillées pour télécharger les fichiers et choisir les bons formats et langages se trouvent sur les consignes aux auteur(e)s qui sont régulièrement mis à jour. Merci de vous familiariser avec ces étapes et de vous y référer chaque fois que cela est nécessaire. Si vous avez besoin d’aide, il est toujours possible de contacter directement par courriel un autre membre de l’équipe de rédaction.

Il y a certaines manipulations techniques à faire à ce stade qui sont les suivantes:

A) Nommer le fichier de la leçon

C’est au rédacteur ou à la rédactrice de proposer un nommage de fichier pour la nouvelle leçon qui se conforme aux consignes suivantes:

Lorsque vous aurez choisi un nom de fichier pour la leçon, merci de l’utiliser aussi pour créer un nouveau dossier dans images, c’est là où seront stockées toutes les images de la leçon. S’il existe aussi des fichiers de données, merci de faire la même action dans le dossier assets.

B) Vérifier la syntaxe Markdown

Les auteur(e)s ont la responsabilité de vérifier que la syntaxe de leur leçon en Markdown est correcte. Si toutes les règles ont été respectées, aucun problème ne devrait se présenter. Au cas contraire, des symboles Markdown restent visibles sur la page, ce qui signifie qu’il y a des erreurs. Des instructions détaillées sur la syntaxe Markdown peuvent se trouver dans nos consignes aux auteur(e)s.

Vous pouvez vérifier rapidement si tout se présente correctement au cours de la soumission en consultant la version du fichier qui s’affiche sur :

http://programminghistorian.github.io/ph-submissions/fr/en-cours/originales/NOM-DE-FICHIER-ICI, s’il s’agit d’une leçon originale; ou sur http://programminghistorian.github.io/ph-submissions/fr/en-cours/traductions/NOM-DE-FICHIER-ICI, s’il s’agit d’une traduction (attention, pas d’extension .md à la fin).

Si cela ne marche pas, merci d’en informer notre équipe technique qui s’occupera du problème.

C) Vérifier la pérennité et l’ouverture internationale

Pour augmenter la durée de vie de nos leçons, les rédacteurs et rédactrices du Programming Historian en français doivent vérifier que sont réunies certaines conditions qui garantissent la pérennité de la leçon. Certes, les mêmes critères ne peuvent pas nécessairement s’appliquer à tous les dépôts, vu que chaque cas est différent. Toutefois, en tenant compte du niveau de difficulté de chaque leçon et du public auquel il s’adresse, les rédacteurs et les rédactrices peuvent s’appuyer sur les critères suivants pour s’assurer de la longévité des leçons après la date de leur publication.

Pour s’adresser à un public international, il faut inviter les auteur(e)s à se conformer aux instructions suivantes dans la mesure du possible:

Les rédacteurs et les rédactrices doivent travailler en étroite collaboration avec les auteur(e)s pour s’assurer que ces critères sont remplis. Quand cela n’est pas possible, il faut clairement en expliquer les raisons dans le ticket de suivi éditorial correspondant.

D) Vérifier les images

Toutes les images doivent porter des noms de fichiers cohérents qui décrivent ce qu’elles représentent. Si une leçon comporte un grand nombre d’images qui se succèdent, l’ordre peut être important (par exemple, une série de prises d’écran). Dans ce cas, il est conseillé d’appliquer un système de nommage de fichiers séquentiel, en utilisant dans l’idéal le nom de fichier de la leçon (ou alors une version abrégée si le titre est trop long), numéroté dans chaque cas pour indiquer l’image (par exemple, counting-frequencies-1.png, counting-frequencies-2.png et ainsi de suite).

Si une leçon utilise un système de nommage d’images séquentiel, il est possible que la numérotation des images se modifie pendant la procédure d’évaluation par les pairs. Avant la publication d’une leçon, nous demandons que tous les noms de fichiers soient mis à jour avec les bons numéros de d’images. Le cas échéant, cela facilite aussi la future mise à jour des leçons. Merci de nous aider, de cette manière, à assurer la pérennité du Programming Historian en français.

Nonobstant le type de nommage des images, sémantique ou séquentiel, celles-ci doivent être placées dans un sous-répertoire du répertoire images. Ce dossier doit être nommé suivant le nom du fichier et de l’URL de la leçon. Merci de vous assurer que les images ont des formats appropriés pour une publication sur le web tel que PNG ou JPEG et ont les bonnes dimensions (à la fois en pixels et en bytes).

Des instructions complètes pour ajouter des images sont disponibles dans les consignes aux auteur(e)s pour les dépôts des leçons.

E) Vérifier les fichiers des données

Comme les images, tous les fichiers des données doivent être hébergés sur le site, plutôt que d’être accessibles via des liens externes, pour en assurer la pérennité. Toutes les données doivent être stockées dans le répertoire assets selon les mêmes règles citées plus haut, mais les auteur(e)s peuvent se sentir libres d’utiliser un titre descriptif pour le fichier de leurs données qui reflète son contenu:

À l’occasion, certaines leçons peuvent requérir des fichiers de données d’une taille qui dépasse les capacités de notre dépôt GitHub. Lorsque c’est le cas, nous recommandons que les auteurs/autrices téléversent leurs données sur Zenodo pour assurer leur archivage pérenne et que le DOI généré par Zenodo soit fourni au rédacteur ou à la rédactrice pour lier le jeu de données au texte de la leçon. Nous recommandons le téléversement sur Zenodo de la version du jeu de données utilisée dans la leçon même lorsqu’une version de ce jeu de données existe déjà dans un dépôt institutionnel, afin d’uniformiser les procédures d’utilisation pour l’ensemble de nos leçons. Le rédacteur ou la rédactrice s’assurera que l’auteur ou l’autrice soit en mesure de naviguer dans l’interface de Zenodo, qui est disponible seulement en anglais, et lui offrira son soutien s’il ou elle ne connaît pas cette langue.

Si l’ensemble des actifs à téléverser sur Zenodo dépasse les 25 Mo, tous les fichiers (même s’il y en a un seul) devront être compressés dans une archive .zip au préalable. Cette archive devrait porter le même nom que le fichier qui contient le texte de la leçon.

F) Vérifier les vidéos et les gifs

L’utilisation de vidéos et de gifs n’est pas vraiment recommandée car elle peut générer plusieurs problèmes. Par exemple, cela prend beaucoup de temps et d’énergie de demander des modifications sur une vidéo pendant la procédure d’évaluation par les pairs. Il est par ailleurs impossible pour l’équipe de rédaction d’effectuer des mises à jour au fil des années pour que la vidéo reste actuelle. En outre, les vidéos nécessitent aussi l’administration d’une chaîne distincte sur YouTube. Enfin, elles ne sont pas imprimables, or beaucoup de nos lecteurs utilisent des copies en PDF ou des imprimés du Programming Historian. Dans ces conditions, les vidéos devraient être utilisées SEULEMENT lorsque cela s’avère absolument nécessaire.

Si un tutoriel contient une vidéo, celle-ci doit être hébergée sur notre chaîne YouTube. À ce jour, cette dernière n’est pas configurée, merci donc d’envoyer un courriel au reste de l’équipe de rédaction lorsque vous recevez une vidéo. Une copie de sauvegarde du fichier devrait aussi être placée dans notre dépôt Github, suivant les mêmes principes de nommage et de stockage qui sont valables pour les images et les données, décrites plus haut, pour faire partie du répertoire ‘assets’:

Acceptation et publication - Liste de vérification éditoriale

Lorsque vous et l’auteur(e) trouvez le tutoriel satisfaisant, l’étape suivante est de transférer la leçon depuis le site des soumissions à notre dépôt principal qui héberge le site web live.

1) Créer une biographie d’auteur(e)

Si l’auteur(e) de la leçon apparaît pour la première fois, il appartient au rédacteur ou à la rédactrice d’ajouter les informations concernant la personne dans le répertoire des auteur(e)s du site. Merci de respecter la syntaxe des exemples qui se trouvent dans le fichier:

- name: Jim Clifford
  team: false
  bio:
      fr: |
          Jim Clifford est professeur adjoint au Département d'histoire de l'Université de la Saskatchewan.

L’espace blanc est important, merci donc de faire attention à ce que l’indentation suive le reste des exemples.

Indiquer l’identifiant orcid n’est pas obligatoire, nous vous encourageons toutefois fortement de le faire, si les auteur(e)s en ont créé un dans le répertoire ORCID (https://orcid.org/). Néanmoins, merci de prendre soin d’utiliser un identifiant ORCID fourni explicitement par l’auteur(e). Évitez par conséquent de le faire sans la confirmation préalable de l’auteur(e) qu’il s’agit du bon identifiant.

2) Ajouter une table de matières à la leçon

Le code suivant doit être ajouté au texte de la leçon, habituellement avant le premier sous-titre:

{% include toc.html %}

3) Ajouter les métadonnées en YAML dans le fichier de la leçon

title: "Votre Titre"
collection: lecons
layout: lesson
slug: par ex. introduction-analyse-des-sentiments
date: AAAA-MM-JJ
translation_date: AAAA-MM-JJ (champ spécifique aux traductions)
authors:
- Prénom Nom
- Prénom Nom, etc
reviewers:
- Prénom Nom
- Prénom Nom, etc
editors:
- Prénom Nom
translator:
- Prénom Nom (champ spécifique aux traductions)
translation-editor:
- Prénom Nom (champ spécifique aux traductions)
translation-reviewer:
- Prénom Nom (champ spécifique aux traductions)
original: slug to original published lesson (champ spécifique aux traductions)
review-ticket: e.g. https://github.com/programminghistorian/ph-submissions/issues/108
difficulty: voir ci-dessous
activity: UNIQUEMENT UN PARMI: acquiring, transforming, analyzing, presenting, sustaining
topics:
 - sujet un (voir ci-dessous)
 - sujet deux
abstract: |
  voir ci-dessous
avatar_alt: Description de l'image de la leçon

difficulty: 2

4) Trouver une image pour représenter une leçon

Pour illustrer nos leçons, nous utilisons des images anciennes qui nous semblent représentatives du contenu des tutoriels. L’ensemble de ces images se trouve dans le répertoire des leçons. Ces images sont choisies par les rédacteurs et les rédactrices.

Ci-dessous quelques sites pour chercher des images:

Merci de prendre soin de trouver une image dont le style est proche de celles déjà utilisées, donc pas de photographie, mais plutôt une image d’illustration de livre, de taille minimale de 200x200 pixels, sans restriction de droits de copyright. Merci de faire attention à ce que les images ne heurtent pas les sensibilités et, en conformité à notre engagement en faveur de la diversité, qu’elles ne reproduisent pas de stéréotypes sexistes ou raciaux.

Par la suite, il faut sauvegarder l’image originale. Le nom du fichier doit être le même que celui de la leçon correspondante, et donc correspondre aussi au slug de son URL, suivi de -original à la fin. Le fichier doit être en format .png. Prenant pour exemple la leçon “Cleaning Data with OpenRefine”, le texte (slug) de son URL est cleaning-data-with-openrefine, par conséquent le nom de fichier de l’image de la leçon doit être cleaning-data-with-openrefine-original.png.

Il faut ensuite créer une nouvelle copie de l’image. Découpez-la en carré en préservant l’essentiel de la représentation puis modifiez la résolution en 200x200 pixels et convertissez-la en mode niveaux de gris. Si besoin, faites des réajustements pour que l’image soit conforme à celles des autres leçons au niveau de la luminosité ou des contrastes. Cette nouvelle image doit être sauvegardée dans un fichier nommé selon le texte de l’URL de la leçon sans oublier que le format doit être en png. Pour reprendre notre exemple précédent, le nom de ce fichier serait donc cleaning-data-with-openrefine.png.

Le fichier de l’image originale doit être téléchargé dans le répertoire gallery/originals, celui de l’image modifiée dans le répertoire gallery. Notez que, s’il s’agit d’une traduction, aucune démarche n’est nécessaire quant à l’image originale.

5) Prévenir le rédacteur ou la rédactrice en chef pour publier

Le rédacteur ou la rédactrice en chef est en charge de la publication de la leçon en déposant les fichiers sur le site web principal et en faisant les vérifications finales. Pour lui faciliter la tâche, merci de publier une liste dans le ticket de la soumission de tous les fichiers à transférer d’un dépôt à l’autre. Habituellement il s’agit:

Mise à part la bio, le reste des éléments devrait exister sous forme de fichiers dans le dépôt ph-submissions. La bio peut être insérée directement dans le ticket.

6) Intégrer votre leçon dans notre bot Twitter

La campagne de promotion sur Twitter, dont les étapes sont décrites ci-dessous, utilise aussi un bot pour faire une communication régulière sur les leçons plus anciennes. Pour y ajouter une nouvelle, vous remplissez une ligne dans ce fichier. Normalement, tous les membres de l’équipe éditoriale doivent pouvoir modifier le tableur. En cas de problème, merci de faire un courriel au groupe Google. Il vous faut ajouter une nouvelle ligne pour votre leçon ) la fin du fichier avec les champs suivants:

Laissez la colonne D vide sans intervenir - ce champ est utilisé par le bot pour enregistrer son progrès à travers la liste. Par ailleurs, cette étape ne remplace pas votre propre promotion de la leçon. Le bot relève les leçons de manière aléatoire une fois par semaine, ce qui signifie que votre leçon pour mettre plusieurs mois avant d’avoir son tweet.

7) Remerciements et promotion de la communication

Il est important d’envoyer un message à toutes les personnes impliquées pour les remercier de leur contribution. En particulier, il faut remercier l’auteur(e) et lui proposer des pistes pour faire la communication autour du cours. Les leçons les plus populaires bénéficient en règle générale de l’énergie investie par leurs auteur(e)s. À titre d’exemple, il est possible d’inviter les auteur(e)s à:

Les leçons sont le fruit d’un investissement considérable, faisons donc de notre mieux pour que les gens puissent les découvrir!

Liste de vérification du rédacteur ou de la rédactrice en chef

Le rédacteur ou la rédactrice en chef a la responsabilité de déposer les fichiers sur le site web principal via un “pull request”. Cela lui permet aussi de prendre connaissance de la nouvelle leçon et de vérifier rapidement que tout se présente bien.

1) Parcourir l’aperçu de la soumission

Vérifiez l’aperçu de la soumission pour repérer des erreurs manifestes, comme des problèmes d’affichage des images ou de formatage. Prévenez-en, le cas échéant, le rédacteur ou la rédactrice en charge de la leçon pour les corriger.

2) Solliciter un identifiant DOI

Prenez soin de solliciter un nouveau DOI pour la leçon selon les instructions du Wiki. L’obtenir ne devrait pas vous prendre plus d’un jour ou deux, en fonction du décalage horaire entre votre pays de résidence et le Royaume-Uni (UTC +1). Vous pouvez commencer à réaliser les étapes suivantes en attendant, sachez toutefois que le processus de modification de la page (build) échouera tant que le DOI n’aura pas été ajouté aux metadonnées.

3) Transférer les fichiers

Le rédacteur ou la rédactrice aurait dû vous laisser une liste claire, dans le ticket de la soumission, avec les fichiers à être publiés. Si ce n’est pas le cas, demandez que cela s’arrange avant d’aller plus loin.

Il existe différentes manières de faire un “pull request” pour publier les fichiers:

  1. Aller au répertoire de votre dépôt local ph-submissions.
  2. Faire git pull pour obtenir le transfert de toutes les modifications récentes sur votre machine (ou faire sync si vous utilisez GitHub Desktop).
  3. Répéter les étapes 1 et 2 pour le dépôt jekyll sur votre machine.
  4. Copier les fichiers des leçons et ceux des images et ressources associées depuis le dépôt ph-submissions de votre machine aux endroits appropriés dans le répertoire de jekyll, toujours sur votre machine (il est possible d’utiliser la commande cp depuis la ligne de commande Unix ou naviguer dans l’arborescence de fichiers de votre interface graphique si vous utilisez GitHub Desktop).
  5. Depuis le répertoire jekyll qui se trouve en local sur votre machine, exécuter git add pour les nouveaux fichiers puis git commit et git push pour soumettre et envoyer les modifications.

Après le transfert de la leçon dans le répertoire jekyll, il faudra aussi archiver la version soumise au dépôt ph-submissions.

  1. Aller au répertoire ph-submissions de votre dépôt local.
  2. Ajouter une nouvelle ligne à l’en-tête YAML de la leçon qui est désormais publiée: redirect_from: "/lessons/SLUG-DE-LA-LEÇON"
  3. Copier la leçon publiée depuis lessons/ vers lessons/published/.
  4. Copier le dossier qui contient les images de la leçon publiée depuis images/ vers images/published/.
  5. Exécuter les commandes git add, git commit et git push pour finaliser toutes les modifications.

4) Vérifier les liens et les en-tête en YAML

Une fois que vous aurez soumis vos modifications à la branche gh-pages du dépôt du programminghistorian, le site web sera automatiquement testé par GitHub Actions. Cette procédure teste trois choses. D’abord, que tout le code en YAML et markdown peut être parsé. Ensuite, que tous les hyperliens du site web pointent vers des pages valides et opérationnelles. Enfin, que les liens internes pointant vers des pages du Programming Historian sont des liens relatifs qui commencent par / plutôt que par https://programminghistorian.org/

Ces opérations visent principalement à vérifier si des URL qui par le passé ont été valides le restent toujours car, souvent, les pages externes au site changent d’adresse ou ne sont plus alimentées. Elles offrent en outre un excellent moyen pour repérer des coquilles qui auraient pu échapper à l’attention des auteur(e)s, rédacteur(trice)s et évaluateur(trice)s. L’état de ces tests, couramment appelé “Build Status” sur GitHub, peut être vérifié en naviguant sur la page du dépôt du programminghistorian et en cliquant sur “Commits” en haut à gauche du menu du code.

GitHub commit menu location

Ainsi, vous pouvez voir la liste de toutes les modifications effectuées sur le dépôt principal, tout comme une icône qui en montre l’état:

Si votre compilation a échoué, il est nécessaire de consulter l’historique pour en repérer la cause.

  1. Cliquer sur l’icône X rouge qui correspond à la modification la plus récente (elle apparaît au plus haut de la page) puis cliquer sur le lien “Details”. Travis details location
  2. Vous serez ainsi dirigés vers la page de l’historique des compilations sur GitHub Actions. Les compilations sont habituellement longues de plusieurs centaines de lignes, mais il faut descendre pour trouver l’information sur l’erreur. Cliquez donc sur le petit cercle gris qui se trouve en haut à droite de l’affichage de l’historique pour afficher le bas de la page. The top of the Travis CI build screen
  3. Il existe deux types d’erreurs: d’abord, si un des champs requis en YAML est manquant (par exemple, si une leçon n’a pas de champ editors), cela apparaîtra en rouge. Les liens qui ne marchent pas seront aussi affichés en rouge et regroupés selon la page à laquelle ils apparaissent. Si des liens de votre leçon renvoient des erreurs, il vaut mieux vérifier à nouveau qu’il n’y a pas de fautes dans l’adresse. Si c’est le cas, il faut faire les corrections nécessaires puis soumettre les modifications au dépôt et attendre que GitHub Actions lance de nouveaux tests. Locating error details in Travis CI build results

5) Tenir au courant le rédacteur ou la rédactrice en charge du suivi éditorial de la leçon

Lorsque la leçon a été publiée, merci d’en informer le rédacteur ou la rédactrice qui en a assuré le suivi éditorial.