Vous pouvez faire un don au Programming Historian

Consignes aux auteur(e)s

Étape 1: proposer une nouvelle leçon

Étape 2: rédaction et mise en forme

Étape 3: soumettre une nouvelle leçon

Ces consignes ont été développées pour vous permettre de comprendre comment s’organise l’écriture d’un tutoriel pour le Programming Historian en français. Elles fournissent des détails pratiques, des informations sur la philosophie de la revue, ses workflows et l’évaluation ouverte par les pairs. Si pour quelque raison que ce soit elles nous vous paraissent pas claires, n’hésitez pas à contacter notre rédacteur/rédactrice en chef.

Étape 1: proposer une nouvelle leçon

Nous vous invitons à nous soumettre des tutoriels pertinents pour les sciences humaines et sociales, qui portent sur une problématique de recherche ou un processus particulier, et qui sont adaptés à n'importe quel niveau de compétence et d'expérience technique. Les tutoriels ont vocation à être pérennes dans le long terme et doivent s'adresser à un public international. La portée et la longueur du tutoriel doivent être appropriées à la complexité de la tâche qui y est expliquée. La longueur des tutoriels ne doit pas excéder 8000 mots (en incluant le code source) et nous encourageons la soumission de leçons plus courtes. Celles qui seraient plus longues sont susceptibles d'être divisées en plusieurs tutoriels.

Si vous avez une idée pour une nouvelle leçon, merci de compléter un formulaire de proposition et contacter notre rédacteur/rédactrice en chef pour discuter de votre idée.

Vous pouvez avoir une meilleure idée de ce que nous publions en consultant nos leçons en ligne, en lisant nos consignes aux évaluateurs et évaluatrices, ou encore en parcourant les leçons en cours de développement. Merci de prendre aussi le temps de consulter notre table de concordance des leçons afin de voir quelles méthodes ont déjà été traitées dans nos tutoriels publiés ou à venir.

Une fois que votre proposition est acceptée, nous allons créer un ticket « Proposition » dans notre dépôt de soumissions avec le titre provisoire de la leçon et les objectifs pédagogiques proposés. Ce ticket sert à signaler le travail en cours alors que vous êtes en train de rédiger votre leçon. Pour éviter d’accumuler les retards, nous vous demandons de soumettre votre leçon dans les 90 jours suivant l’acceptation de votre proposition. Pendant cette période, votre point de contact sera notre rédactrice en chef ou un autre membre de l’équipe désigné par celle-ci.

Étape 2: rédaction et mise en forme

Ce guide de style présente notre approche et notre charte éditoriale à l’attention des auteur(e)s. En respectant ces principes, vous nous aidez à conserver la cohérence des contenus du Programming Historian en français.

La section comprend trois parties, que nous vous remercions de lire avant d’écrire et après avoir achevé votre contribution :

A. Style de rédaction et public ciblé

Cette partie aborde des questions générales de style pour vous aider à mieux répondre aux attentes de notre lectorat et de notre équipe éditoriale. Elle fournit des informations élémentaires sur le style et le ton à adopter lors de la rédaction, l’engagement en faveur du libre accès et des logiciels libres, la nécessité de s’adresser à un lectorat international, le besoin d’écrire un texte qui puisse durer dans le temps, et les choix à faire quant aux données mobilisées dans les leçons. Nous vous conseillons de bien lire cette partie lorsque vous vous projetez dans l’écriture d’une leçon puis de la relire avant de soumettre votre texte pour avoir la certitude que vous en avez tenu compte.

Langue et style

À tout moment, en cas de doute, vous pouvez vous adresser au membre de notre équipe qui assure le suivi éditorial de votre leçon pour obtenir plus de clarifications, si nécessaire.

Open source, libre accès

Le Programming Historian en français adhère aux principes de l’open source et du libre accès. Toutes les leçons doivent utiliser des langages de programmation et des logiciels à code source ouvert et libres dans la mesure du possible. Cela minimise les coûts pour toutes les parties impliquées dans la création et la réception des leçons et garantit leur utilisation la plus large possible.

Les auteur(e)s détiennent les droits de propriété intellectuelle et cèdent à la revue le droit de première publication, l’œuvre étant simultanément placée sous licence Creative Commons - Attribution 4.0 International CC-BY 4.0. Les auteur(e)s ont le droit de publier et de mettre à disposition leur œuvre par voie numérique au travers de dépôts institutionnels/disciplinaires ou de leur propre page web.

Nous demandons aux auteur(e)s, aux traducteurs et aux traductrices de compléter un formulaire de cession non exclusive de droits d’auteur et d’autorisation de publication. Veuillez envoyer le formulaire à notre assistante éditoriale.

Écrire pour un public international

Le lectorat du Programming Historian vient du monde entier et travaille au sein d’environnements culturels variés. Merci de garder à l’esprit que le Programming Historian en français s’adresse à tous les pays francophones et que, de plus, votre leçon est susceptible d’être traduite dans l’une des langues de nos différentes publications. C’est pourquoi les auteur(e)s doivent veiller à écrire leurs leçons de façon à ce qu’elles soient accessibles à un lectorat diversifié. Merci donc de faire preuve d’un esprit large et de faire attention aux conseils suivants :

Écrire de manière durable

Le Programming Historian en français s’efforce de publier des leçons qui restent utiles à notre lectorat sur le long terme. Pour assurer la création de leçons pérennes, nous vous demandons de garder à l’esprit un certain nombre de consignes lors de leur rédaction :

B. Règles typographiques

Cette partie se concentre davantage sur des conventions d’écriture à propos des dates, des nombres, des en-têtes, des listes, de l’usage des majuscules ou de la ponctuation, ainsi que de l’application de l’écriture inclusive. Vous pouvez vous y référer avant et après l’écriture de votre brouillon.

Dates et heures

Nombres

En-têtes

Les en-têtes ne doivent pas faire appel à des polices de caractères spécifiques ou à des propriétés telles que l’italique ou le gras.

Les titres doivent immédiatement précéder le corps du texte de l’en-tête.

Ne pas faire suivre un titre d’une mise en garde ou d’un autre titre sans un court texte introductif ou descriptif.

Listes

Nous utilisons les listes à puces ou à nombres. Les items de listes doivent être limités à une phrase. Ils sont traités comme des entités séparées et ne doivent pas être enchaînés avec de la ponctuation et des conjonctions.

Ne pas écrire:

Écrire:

Ou bien écrire:

  1. Voici un item
  2. Voici un autre item
  3. Voici un dernier item

Ponctuation

L’utilisation d’une espace insécable fine avant le point d’exclamation est recommandée en France, au Québec et en Suisse, mais sa suppression est tolérée dans les deux derniers pays, enfin, en Belgique il n’y a pas d’espacement. Merci de consulter la partie spéciale sur l’espacement à la fin de cette section.

Règles d’espacement avant/après les principaux signes de ponctuation et autres symboles

Les règles typographiques ne coïncident pas toujours entièrement entre les différents pays francophones, bien qu’elles se recoupent dans leurs grandes lignes. Merci de retenir que nous conseillons l’utilisation de l’espace insécable avec les guillemets français, devant le symbole de pourcentage et devant le deux-points. Aussi, d’insérer si possible l’espace insécable fine devant le point-virgule, le point d’exclamation et le point d’interrogation, si votre éditeur de texte le permet ou à l’aide des codes suivants :

Merci de vous référer aux recommandations sur l’espacement de l’Office québécois de la langue française.

Usage des majuscules

Les majuscules, à utiliser avec parcimonie dans la prose courante, peuvent se diviser en trois catégories :

Les majuscules sont aussi concernées par les accents, le tréma ou la cédille, même dans le cas des abréviations, mais pas pour les sigles et les acronymes. Les différents cas décrits ci-dessous résument les particularités dans l’usage des majuscules en français.

Pour plus de précisions, vous pouvez consulter la banque de dépannage linguistique de l’Office québécois de la langue française, avec une liste de l’emploi de la majuscule pour des types de dénominations et une autre pour les noms particuliers.

Références bibliographiques

Écriture inclusive

Nous appliquons l’écriture inclusive suivant les consignes de l’Office québécois de la langue française sur la formation des noms féminins et la rédaction épicène, mises en place en 2002, ainsi que du Guide d’aide à la féminisation des noms de métiers, titres, grades et fonctions, publié par l’Institut national de la langue française en 1999. Ces deux textes se recoupent largement et constituent des guides de base pour l’équipe du Programming Historian en français. En revanche, nous n’avons pas recours à l’utilisation du point médian (ou point milieu) ou de tirets. Ainsi, nous évitons d’écrire « les historien·ne·s » ou « les historien-ne-s »; nous privilégions à la place « les historiens et historiennes » ou encore « les historien(ne)s », pour éviter d’alourdir le texte. De même, nous pouvons faire recours à l’emploi d’un nom collectif, en parlant, par exemple, du lectorat du Programming Historian plutôt que des lecteurs et des lectrices ou des utilisateurs et des utilisatrices.

C. Mise en forme

Cette section finale couvre les questions de mise en forme nécessaires pour soumettre une leçon. Merci de la lire attentivement aussi bien avant de vous lancer dans l’écriture qu’après avoir achevé votre première version. En cas d’erreur, vous pouvez toujours apporter des corrections au début du processus d’évaluation par les pairs à l’aide d’une prévisualisation de votre leçon.

Écrire en Markdown

Toutes les leçons doivent être écrites en Markdown. Nous fournissons un modèle que vous pouvez utiliser pour écrire votre leçon.

Markdown est un langage de balisage. Vous pouvez l’écrire facilement en utilisant un éditeur de texte de votre choix. Attention, Microsoft Word et Open Office, qui ne sont pas des éditeurs mais des traitements de texte, sont à éviter. Nous recommandons plutôt l’utilisation des éditeurs suivants : Atom, TextWrangler, TextEdit, MacDown ou Notepad++. Si besoin, vous pouvez consulter notre leçon introductive Débuter avec Markdown.

Votre leçon doit être sauvegardée dans un fichier en format .md. Le nom de fichier définit l’URL de la leçon publiée, c’est pourquoi vous devez le nommer :

Caractères en gras, italique et surlignés

Caractères en gras

Caractères en italique

Caractères surlignés

Les caractères surlignés ne sont pas utilisés.

Alertes, messages importants

Si vous souhaitez attirer l’attention des lecteurs, vous pouvez ajouter un bloc à part dans le texte :

<div class="alert alert-warning">
 Attention à ces instructions, elles sont très importantes&#x202F;!
</div>

Figures et images

Les images doivent pouvoir aider votre lectorat à mieux comprendre les étapes de votre leçon, elles ne doivent pas être purement illustratives. Si vous souhaitez en fournir avec votre leçon, nommez-les de manière ordonnée NOM-DE-LEÇON1.jpg, NOM-DE-LEÇON2.jpg, etc. puis, dans le texte, rappelez-les en tant que figure 1, figure 2… Toutes les figures doivent être accompagnées d’une brève légende et, le cas échéant, de notes. Vous devez disposer du droit de publier toute image que vous fournissez.

Veillez à utiliser un format adapté à la publication web tel .png or .jpg et à réduire les grandes images à un maximum de 840px sur la longueur. Cela est important pour les lecteurs et les lectrices qui disposent des connexions internet à bas débit.

Les images doivent être fournies dans un répertoire qui porte le même nom que votre fichier .md de leçon. Le rédacteur ou la rédactrice en charge du suivi éditorial de votre leçon peut vous aider à téléverser les images lorsque vous soumettez la leçon.

Vous pouvez insérer une image dans votre texte à l’aide de cette syntaxe :

{% include figure.html filename="IMAGE-FILENAME" caption="VOTRE TITRE, AVEC \"CODE D'ÉCHAPPEMENT\" POUR LES GUILLEMETS" %}

N’oubliez pas que les guillemets à l’intérieur des titres des figures doivent être échappés à l’aide d’une barre oblique inverse, comme dans l’exemple ci-dessus. Il est important de noter que, lorsque les images sont encodées de cette manière, elles ne sont pas visibles dans la prévisualisation de votre leçon, mais votre rédacteur ou rédactrice s’assurera qu’elles soient affichées correctement lorsque la leçon sera publiée.

Blocs de code

Si vous voulez inclure des lignes de code dans une leçon, il faut les distinguer clairement de la prose :

Un bloc de code multilignes s'affiche de cette manière

` et le code sur la même ligne s’affiche ainsi`.

– Merci de suivre les bonnes pratiques pour écrire votre code :

JavaScript:

abstract, arguments, await, Boolean, break, byte, case, catch, char, class, const, continue, debugger, default, delete, do, double, else, enum, eval, export, extends, false, final, finally, float, for, function, goto, if, implements, import, in, instanceof, int, interface, let, long, native, new, null, package, private, protected, public, return, short, static, super, switch, synchronized, this, throw, throws, transient, true, try, typeof, var, void, volatile, while, with, yield.

Python 2:

and, as, assert, break, class, continue, def, del, elif, else, except, exec, finally, for, from, global, if, import, in, is, lambda, not, or, pass, print, raise, return, try, while, with, yield.

Python 3:

and, as, assert, break, class, continue, def, del, elif, else, except, False, finally, for, from, global, if, import, in, is, lambda, nonlocal, None, not, or, pass, raise, return, True, try, while, with, yield.

R:

break, else, for, FALSE, function, if, in, Inf, NA, NA_character_, NA_complex_, NA_integer_, NA_real_, NaN, next, NULL, repeat, TRUE, while.

Étape 3: soumettre une nouvelle leçon

Une fois que vous avez vérifié que votre leçon a été préparée en suivant les consignes données ci-dessus, nous vous conseillons de la faire relire et éventuellement d’apporter des corrections pour l’améliorer. Ainsi, l’évaluation ouverte par les pairs que nous allons organiser par la suite pourra se concentrer sur le fond, plutôt que sur la forme, afin de vous aider à produire la version la plus solide possible de votre leçon.

Lorsque vous êtes prêt(e) à la soumettre, merci d’envoyer tous les fichiers (texte, images, données…) au rédacteur ou à la rédactrice en charge du suivi éditorial de votre leçon, qui les téléversera pour vous dans notre dépôt dédié à l’évaluation par les pairs sur Github. Voici comment procéder de votre côté:

  1. Obtenir accès à notre dépôt d’évaluation: pour cela il suffit de créer un compte gratuit sur Github et de le communiquer à votre rédacteur ou rédactrice, qui va ensuite vous ajouter comme collaborateur ou collaboratrice dans le dépôt [ph-submissions]. Ce n’est pas à vous de faire le téléversement initial des fichiers, mais l’accès au dépôt est nécessaire pour que vous puissiez par la suite apporter des modifications et des mises à jour.
  2. Préparer vos fichiers: vous avez probablement des images qui accompagnent votre leçon. Merci de vérifier que tous les fichiers images sont nommés de manière appropriée, en accord avec les [conventions de nommage spécifiées ci-dessus]. Ces fichiers doivent nous parvenir dans un dossier unique compressé. Si vous avez en plus des fichiers de données, merci de nous envoyer ces fichiers aussi dans un dossier compressé distinct.
  3. Envoyer un message électronique: informez votre rédacteur ou rédactrice que vous êtes prêt(e) à soumettre votre leçon, en joignant le fichier de celle-ci et, le cas échéant, les dossiers des fichiers images et données.
  4. Participer à la discussion: le rédacteur ou la rédactrice en charge du suivi éditorial de votre leçon déposera vos fichiers dans notre dépôt de soumissions en faisant quelques premières modifications si nécessaire (métadonnées, syntaxe Markdown etc). Ensuite, un ticket sera ouvert pour l’évaluation ouverte de votre leçon, pendant laquelle vous avez la possibilité d’échanger avec celles et ceux qui participent au processus.
  5. Apporter des modifications: si le dépôt initial des fichiers est fait par votre rédacteur ou rédactrice assigné(e), le processus éditorial peut néanmoins entraîner le besoin d’apporter des modifications supplémentaires de votre côté. Toutes les révisions se font directement par les auteur(e)s sur les fichiers versés dans notre dépôt pour avoir la certitude que vous travaillez sur la version la plus récente du fichier de la leçon.

Le processus de l’évaluation ouverte par les pairs

Une fois que votre rédacteur ou rédactrice assigné(e) aura déposé et formaté vos fichiers de manière appropriée, vous recevrez un lien de prévisualisation de la leçon qui vous permettra de vérifier aussi de votre côté que tout se présente correctement ; si ce n’est pas le cas, vous pouvez apporter des corrections.

L’évaluation par les pairs a lieu dans le cadre d’un ticket Github qui prend ainsi la forme d’un forum de discussion ouverte. Merci de garder à l’esprit que l’évaluation par les pairs se fait publiquement et qu’elle reste disponible à la consultation publique ; le ticket en est l’enregistrement. Si pour quelque raison que ce soit vous n’êtes pas à l’aise ou souhaitez une évaluation par les pairs non publique, merci de prendre contact avec votre rédacteur ou rédactrice assigné(e).

Le processus de l’évaluation se passe habituellement en trois étapes :

1) Le rédacteur ou la rédactrice assigné(e) à votre leçon en fait une première lecture attentive en testant les manipulations proposées. Vous êtes à ce stade susceptible de recevoir un premier retour qui pourrait solliciter votre réponse. L’objectif de ce premier retour est de se garantir la pertinence de votre leçon pour le lectorat du Programming Historian en français et qu’elle est fonctionnelle avant d’être proposée à l’évaluation externe. Vous avez normalement un mois pour répondre à cette première évaluation.

2) Ensuite, votre rédacteur ou rédactrice assigné(e) propose la leçon à l’évaluation formelle par les pairs. Cela implique l’invitation d’au moins deux évaluateurs ou évaluatrices externes, mais potentiellement aussi la participation d’une communauté plus large, car tout commentaire est bienvenu (pourvu que les règles de bonne conduite, explicitées dans le ticket, soient observées). En général, nous accordons aux évaluateurs et évaluatrices un délai d’un mois pour fournir leurs commentaires, il peut néanmoins arriver que ce délai ne soit pas respecté pour des raisons indépendantes de la volonté des personnes impliquées au processus. Vous devez attendre l’ensemble des relectures et les instructions consécutives de votre rédacteur our rédactrice assigné(e) avant d’aller plus loin. Parfois, il peut s’agir de simples suggestions d’apporter certaines modifications, mais il peut aussi être question de révisions majeures ou de repenser la leçon. Selon les évaluations des pairs et la nature des questions soulevées, il se peut que vous ayez à réviser le tutoriel plus qu’une fois. Toufois, votre rédacteur ou rédactrice assignée(e) veillera à ce que vous receviez une ligne directrice claire pour que la leçon soit publiée. Par ailleurs, il est toujours possible de retirer votre leçon du processus de l’évaluation, si tel est votre choix.

3) Au bout de ce processus, si tous les critères sont remplis, votre rédacteur ou rédactrice assignée(e) donne le feu vert pour la publication. C’est ensuite au rédacteur ou à la rédactrice en chef de relire la leçon pour s’assurer de sa conformité aux consignes aux auteur(e)s et aux standards du Programming Historian. Parfois des révisions et des corrections supplémentaires peuvent être nécessaires à ce stade pour que la leçon puisse être publiée. Une fois que le rédacteur ou la rédactrice en chef juge la version révisée satisfaisante, la leçon peut être mise en ligne. Votre rédacteur ou rédactrice assigné(e) vous fournira toute information nécessaire à ce stade.

N’hésitez pas à consulter nos consignes aux évaluateurs et évaluatrices afin de vous familiariser avec notre processus de révision et de publication.

Si jamais vous êtes dans l’incertitude sur comment procéder, n’hésitez pas à poster votre question sur le ticket d’évaluation, un membre de notre équipe vous apportera des réponses dans les délais les plus brefs possible. Nous faisons de notre mieux pour répondre au bout de quelques jours.

Que se passe-t-il une fois votre leçon publiée ?

Il nous arrive de recevoir des retours de notre lectorat nous signalant des erreurs dans nos leçons. Le cas échéant, notre assistante éditoriale va ouvrir un ticket sur GitHub pour confirmer si l’erreur signalée est due à une mauvaise manipulation de l’utilisateur ou de l’utilisatrice (modification du code, du jeu de données…) ou à un problème de la leçon. Dans ce dernier cas, notre assistante éditoriale va tester à nouveau la leçon et chercher une solution. Dans le cadre de ce processus de maintenance de nos leçons, nous pouvons être amenés à vous contacter aussi pour solliciter votre avis. Si une solution est impossible à trouver, nous proposerons de faire afficher un avertissement expliquant que certain(e)s de nos utilisateurs et utilisatrices pourraient rencontrer des problèmes. Lorsque cela est possible, l’avertissement devrait inclure des liens vers des ressources qui pourraient permettre aux utilisateurs et utilisatrices de trouver une solution.

Nous interpeller

Notre équipe de bénévoles fait de son possible pour garantir l’évaluation rigoureuse, collégiale et efficace des auteur(e)s par les pairs. Toutefois, il peut y avoir des failles, c’est pourquoi nous souhaitons que les auteur(e)s nous aident à maintenir un haut niveau de service. Si, pour quelque raison que ce soit, vous estimez ne pas avoir été traité(e) correctement, ou ne comprenez pas trop quel est votre rôle ou ce qu’on attend de vous, ou encore si vous considérez que l’évaluation présente des retards injustifiés ou que quelqu’un a été incorrect(e) avec vous, enfin, pour quel autre souci que ce soit, n’hésitez pas à nous en tenir informés afin que nous puissions agir.

Exprimer des réserves n’a AUCUN impact négatif sur le processus et le résultat de l’évaluation par les pairs.

Pour ce faire, vous avez plusieurs points d’entrée - sentez-vous libre de contacter la personne avec laquelle vous êtes le plus à l’aise :

Nous œuvrons pour que tout se passe au mieux pour vous, mais si jamais vous estimez vous trouver dans une situation peu confortable, nous vous remercions de nous aider à y remédier et à améliorer les choses.