Consignes aux rédacteurs et les 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 / 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(e) de nos rédacteur(trice)s 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 mis à 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 Amanda VIsconti. 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 d’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 dispositif de médiation (Amanda Visconti - http://programminghistorian.org/fr/equipe-projet). 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 propoposition 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 contater 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 la médiatrice @amandavisconti.

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.

Après qu’une leçon a été déposée, le rédacteur ou la rédactrice doit créer un ticket d’évaluation en fermant celui de la proposition.

É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 gratuite.

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 le tutoriel intitulé '[TITRE DE LA LEÇON]' par [NOM D'UTILISATEUR/UTILISATRICE GITHUB DE L'AUTEUR(E)]. La leçon préparée par [NOM D'UTILISATEUR/UTILISATRICE GITHUB DU TRADUCTEUR OU DE LA TRADUCTRICE]) est actuellement en cours d'évaluation et peut être consultée ici:

http://programminghistorian.github.io/ph-submissions/lessons/[URL to lesson]

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 à @amandavisconti si vous souhaitez que notre médiatrice intervienne.

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 [Amanda Visconti](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/lecons/NOM-DU-FICHIER-ICI (attention, pas d’extension .md à la fin)

Si cela ne marche pas, merci d’en informer Matthew Lincoln qui s’occupera du problème.

C) Vérifier la pérennité et de 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éante, 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:

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

L’utilisation de vidéos et de gifs n’est pas vraiement 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) Transférer les fichiers

La manière la plus simple pour publier la leçon est d’utiliser git depuis la ligne de commande. Les instructions suivantes supposent que vous avez déjà cloné les dépôts jekyll and ph-submissions en local sur votre machine. Notre leçon sur l’utilisation de l’application GitHub Desktop peut vous être utile, si cela est tout nouveau pour vous. Si vous n’êtes pas confiant(e) sur comment procéder ou si vous avez des questions, merci de contacter Matthew Lincoln pour obtenir de l’aide.

  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.

2) 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:
      en: |
          Jim Clifford is an assistant professor in the Department of History
          at the University of Saskatchewan.

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

3) 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 %}

4) Ajouter les évaluateurs/évaluatrices et rédacteurs/rédactrices dans le fichier YAML

Il est important de reconnaître le travail accompli par les personnes qui assurent l’évaluation par les pairs et le suivi éditorial des leçons. Merci d’ajouter les noms des évaluateurs/évaluatrices, ainsi que de toute personne ayant contribué à l’évaluation ouverte, dans le fichier YAML qui correspond au haut de la page du tutoriel. Par ailleurs, merci de créer un champ editors pour insérer votre nom et celui d’autres membres de l’équipe de la rédaction qui a eu un rôle actif dans la publication de la pièce. Des instructions pour le formatage des fichiers YAML sont disponibles dans les consignes aux auteur(e)s.

5) Insérer un indice de difficulté dans le fichier YAML

Pour aider les lecteurs et les lectrices repérer les leçons qui conviennent mieux à leur niveau de besoins et de compétences, le fichier YAML du tutoriel contient une information de type “Recommandé aux utilisateurs de niveau __ “. Il existe à l’heure actuelle trois niveaux définis qui sont codés comme suit: 1 (débutant), 2 (intermédiaire), 3 (avancé). Pour insérer cette information dans le fichier YAML, merci d’ajouter:

difficulty: 1

6) Ajouter le ticket d’évaluation dans le fichier YAML

Pour assurer la pleine transparence autour de la procédure de l’évaluation, merci de créer un champ review-ticket dans le fichier YAML pour fournir l’URL qui correspond au ticket d’évaluation qui se trouve sur le dépôt des soumissions ph-submissions. En insérant cette information, un lien sera créé pour pointer vers le ticket d’évaluation depuis la leçon.

7) Mettre à jour le champ de date dans le fichier YAML

Mettez à jour la date dans le fichier YAML pour indiquer quand la leçon a été transférée dans le dépôt de jekyll et intégrée au site web principal.

8) Autres touches finales pour le fichier YAML

Selon l’exemple ci-dessous, merci de vous assurer que tous les champs de l’en-tête du fichier de la leçon sont correctement remplis. Le plus souvent, les champs à être complétés ou modifiés à ce stade sont les suivants:

Voici ci-dessous un en-tête achevé qui peut servir d’exemple:

---
title: "Getting Started with Topic Modeling and MALLET"
collection: lessons
layout: lesson
slug: topic-modeling-and-mallet
date: 2012-09-02
authors:
- Shawn Graham
- Scott Weingart
- Ian Milligan
reviewers:
- John Fink
- Alan MacEachern
- Adam Crymble
editors:
- Adam Crymble
review-ticket: https://github.com/programminghistorian/ph-submissions/issues/14
difficulty: 2
activity: analyzing
topics: [distant-reading]
abstract: "In this lesson you will first learn what topic modeling is and why you might want to employ it in your research. You will then learn how to install and work with the MALLET natural language processing toolkit to do so."
---

9) 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 correpospondante, 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.

10) 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.

11) 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 Travis CI (Continuous Integration). Cette procédure teste deux 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.

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 Travis CI et 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 Travis CI. 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 Travis CI lance de nouveaux tests. Locating error details in Travis CI build results

12) 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!