Guía para editores

Esta página contiene instrucciones detalladas dirigidas a los editores de The Programming Historian en español durante el proceso de revisión por pares.

El rol del editor

Gracias por editar una lección para The Programming Historian en español. Estamos muy agradecidos por tus esfuerzos. Esta guía está pensada para garantizar que autores, traductores, editores y revisores tengan una experiencia justa y coherente. Si tienes alguna pregunta sobre esta guía, por favor, contacta con algún miembro del equipo o publica una pregunta en nuestro repositorio de GitHub. También puedes escribirnos si crees que esta guía debe ser actualizada o mejorada.

Contenidos

Tanto si estás editando una traducción como si estás editando una lección nueva el proceso sigue unas mismas líneas de acción; nuestro objetivo como editores no es supervisar, como se suele hacer en las revistas tradicionales sino ofrecer ayuda durante todo el proceso de escritura, traducción y publicación. Por eso es recomendable que te familiarices con la Guía para autores y traductores.

Si recibes una propuesta de lección nueva, asegúrate de que el autor te proporciona una idea clara del contenido antes de que empiece a escribir el tutorial. Si un tema no es adecuado para The Programming Historian en español nuestro trabajo es decírselo al autor antes de que empiece a escribir la lección. Con esto pretendemos ahorrarnos tiempo y energía. Una vez hemos hablado con el autor y hemos evaluado su propuesta, podemos seguir adelante con el proceso de revisión.

Espacios seguros

En The Programming Historian en español estamos comprometidos con ofrecer un espacio seguro en el que se puedan intercambiar ideas sin miedo a sentirse acosado o sin sufrir algún tipo de abuso. El editor cumple un rol fundamental a la hora de asegurarse que el espacio en que tienen lugar las conversaciones no sea dañino para los participantes. En otras palabras, tu rol, como editor, también consiste en reforzar nuestra política en contra del acoso en todo momento. Si necesitas ayuda, por favor, contacta con otro editor. Puedes leer más sobre este tema, en inglés, en nuestro blog.

Política contra el acoso

En esta sección encontrarás una declaración de los principios que deben regir The Programming Historian en español; también ofrece una pauta sobre el tono y el estilo que debiera predominar en todos los intercambios que tienen lugar en nuestros foros entre traductores, autores, revisores y editores.

El objetivo de The Programming Historian en español es ofrecer un entorno abierto en el que la comunidad de participantes sea libre para analizar ideas, realizar preguntas, sugerir cambios, y pedir aclaraciones; también queremos que sea un espacio libre de acoso y hostigamento para todo el mundo con independencia de su género, identidad, orientación sexual, minusvalía, apariencia física, tamaño corporal, raza, edad, religión o conocimientos informáticos. No se tolerará ningún tipo de acoso o ataque ad hominem. Los participantes que violen esta regla podrán ser expulsados del proceso editorial a discreción del equipo editorial. Si presencias o sientes que has sido víctima de algún tipo de acoso, por favor, contacta con nuestros ombudspersons María José Afanador-Llach o Víctor Gayol.

Seguimiento de lecciones

Una vez se ha aceptado una propuesta de lección, el editor aclarará al autor cuáles son los objetivos y establecerá una fecha de entrega. El plazo recomendado es de 90 días para las lecciones nuevas; sin embargo, estos tiempo se pueden adaptar a cada caso.

A continuación, el editor creará un issue en el repositorio de GitHub con la etiqueta “proposals” para las nuevas lecciones. La plantilla viene incluida por defecto en el issue, pero también se puede copiar el texto que se encuentra más abajo.

*The Programming historian* ha recibido una propuesta de lección con el título provisional ‘Título provisional de la lección’ por parte de ‘Nombre del autor o autores’. Los objetivos de la lección son:

- objetivo nº1
- objetivo nº2
- objetivo nº3

A fin de promover una publicación a tiempo, se ha acordado que la lección se entregará en un plazo de [90 days por defecto o más tarde si se ha establecido así con el autor]. El autor o autores contactará con antelación con el editor si no puede cumplir con la fecha de entrega y necesita una ampliación.

Si la lección no es entregada en la [fecha acordada], el editor intentará contactar con el autor o autores de la lección. Si no recibe noticias, el ticket se cerrará. Éste podrá abrirse en el futuro a petición del autor o autores.

El principal contacto para esta lección es [nombre del editor]. Si se produce algún problema, el autor puede contactar con nuestros ’ombudspersons' (María José Afanador-Llach o Víctor Gayol - http://programminghistorian.org/es/equipo-de-proyecto).

Este texto, sin embargo, puede editarse y adaptarse a las necesidades para reflejar más objetivos o lo que se ha negociado entre el editor y el autor.

Una vez la lección haya sido entregada, el editor creará un ticket de revisión para la lección y cerrará el issue correspondiente a la propuesta inicial.

Revisión por pares en abierto

The Programming Historian en español se sirve de un modelo de revisión por pares en abierto; creemos que esto incentiva el respeto y la generación de ideas. Sin embargo, los autores y traductores también tienen derecho a tener un proceso de revisión tradicional, es decir, mediante mensajes privados. Existen muchas razones por las que alguien podría dudar a la hora de iniciar un proceso de revisión por pares en abierto; por eso, animamos a los autores y traductores a que elijan la opción con la que se sientan más cómodos.

Antes de solicitar revisiones externas, el editor debe leer y probar el tutorial, y utilizar su experiencia previa para ayudar al autor o al traductor a realizar mejoras iniciales (si es necesario). En una lección nueva, los editores suelen intervenir para aclarar la audiencia objetiva de la lección, o bien para identificar frases difíciles de entender, tecnicismos que se podrían evitar, o pasos que requieren mayor número de explicaciones (o adaptaciones teniendo en cuenta el contexto cultural hispánico, si se trata de una traducción). Esta revisión inicial es importante porque permitirá a los revisores externos centrarse en la mejora de la lección. Todo esto se realiza, por lo común, en abierto, en nuestra plataforma de envíos (ver más abajo), pero si el autor o traductor lo requiere también es posible establecer un canal de comunicación privado.

Cuando el traductor o el autor ha revisado la lección siguiendo el consejo del editor, se invitarán a dos revisores externos. La decisión sobre los revisores externos depende del editor; no obstante, se tendrá en cuenta nuestro compromiso con la diversidad a la hora de elegir los revisores. Como editor, te animamos a que te preguntes si has hecho todo lo posible para elegir revisores de género, nacionalidad, raza, edad, o formación académica diversa. En otras palabras, evita elegir revisores que sean como tú. Al contactar con los revisores, por favor, proporciona la guía para revisores y fija una fecha límite para completar la revisión (un mes, por lo general), a fin de asegurarnos de que el proceso de publicación no se alargue de manera innecesaria.

Al recibir una lección o traducción nueva, el editor iniciará un nuevo issue en nuestro repositorio de envíos en Github, en donde tendrá lugar el proceso de revisión. De esta manera, todos los participantes podrán seguir la conversación y recibirán los mensajes. Los editores, traductores y autores deberán registrarse en GitHub (si no lo han hecho ya) y acceder al repositorio con su cuenta.

Comentarios iniciales

Cuando recibas una propuesta de traducción o creación de una lección nueva, tu primer mensaje debe utilizar la plantilla que describe el rol del editor y el proceso de revisión por pares, así como información necesaria en caso de que la revisión sufra algún incidente. Por favor, adapta la plantilla correspondiente para que aparezca al inicio del issue.

En el caso de una traducción, utiliza esta plantilla:


'The Programming Historian en español' ha recibido la siguiente propuesta de traducción [TÍTULO DE LA TRADUCCIÓN] de la lección [TÍTULO DE LA LECCIÓN] por parte de [NOMBRE DE USUARIO GITHUB DEL TRADUCTOR]. Esta traducción se encuentra en estos momentos en fase de revisión y puede leerse en:

https://github.com/programminghistorian/ph-submissions/tree/gh-pages/es/traducciones/URL-a-la-traducción

Por favor, estás en libertad de utilizar los números de línea proporcionados en la vista previa, si eso ayuda a señalar mejor tus comentarios. Pero puedes estructurar tu revisión como mejor te parezca.

En adelante, intervendré como editor durante el proceso de revisión. Tras haber leído la lección y haber enviado mis comentarios al traductor, mi rol consistirá en solicitar otra revisión por parte de uno de los miembros de nuestro comité editorial y gestionar las conversaciones que se produzcan en este foro.

Otros miembros de nuestra comunidad también están invitados a ofrecer sus comentarios de una manera constructiva; los comentarios deberán publicarse en este hilo de conversación, por lo que se recomienda haber leído nuestra guía para revisores (/es/guia-para-revisores) y tener en cuenta nuestra política contra el acoso (ver más abajo). No se aceptarán más comentarios por parte de la comunidad tras la publicación de la segunda revisión formal a fin de que el traductor pueda empezar a trabajar en los cambios solicitados. Cuando esto ocurra, publicaré un anuncio aquí.

Asimismo, me comprometo a mantener la conversación abierta a todo el mundo en GitHub. Pero si alguno de los participantes quiere ponerse en contacto en privado conmigo, puede escribirme un correo electrónico. También es posible contactar con nuestros 'ombudpersons'.

Política contra el acoso
_

El objetivo de 'The Programming Historian en español' es ofrecer un entorno abierto en el que la comunidad de participantes sean libres para analizar ideas, realizar preguntas, sugerir cambios, y pedir aclaraciones; también queremos que sea un espacio libre de acoso y hostigamento para todo el mundo con independencia de su género, identidad, orientación sexual, minusvalía, apariencia física, tamaño corporal, raza, edad, religión o conocimientos informáticos. No se tolerará ningún tipo de acoso o ataque *ad hominem*. Los participantes que violen esta regla podrán ser expulsados del proceso editorial a discreción del equipo editorial. Si presencias o sientes que has sido víctima de algún tipo de acoso, por favor, contacta con nuestros 'ombudspersons' (María José Afanador-Llach o Víctor Gayol - http://programminghistorian.org/es/equipo-de-proyecto).

Para las lecciones nuevas, utiliza la siguiente plantilla:


'The Programming Historian en español' ha recibido la siguiente propuesta de lección [TÍTULO DE LA LECCIÓN] por parte de [NOMBRE DE USUARIO GITHUB DEL AUTOR]. Esta lección se encuentra en estos momentos en fase de revisión y puede leerse en:

https://github.com/programminghistorian/ph-submissions/tree/gh-pages/es/lecciones/URL-a-la-lección

Por favor, estás en libertad de utilizar los números de línea proporcionados en la vista previa, si eso ayuda a señalar mejor tus comentarios. Pero puedes estructurar tu revisión como mejor te parezca.

En adelante, intervendré como editor durante el proceso de revisión. Mi rol consistirá en solicitar dos revisiones externas y gestionar las conversaciones que se produzcan en este foro. He leído la lección y ya le he hecho llegar mis comentarios al traductor.

Otros miembros de nuestra comunidad también están invitados a ofrecer sus comentarios de una manera constructiva; los comentarios deberán publicarse en este hilo de conversación, por lo que se recomienda haber leído nuestra guía para revisores (/es/guia-para-revisores) y tener en cuenta nuestra política contra el acoso (ver más abajo). No se aceptarán más comentarios por parte de la comunidad tras la publicación de la segunda revisión formal a fin de que le autor pueda empezar a trabajar en los cambios solicitados. Cuando esto ocurra, publicaré un anuncio aquí.

Asimismo, me comprometo a mantener la conversación abierta a todo el mundo en GitHub. Pero si alguno de los participantes quiere ponerse en contacto en privado conmigo, puede escribirme un correo electrónico. También es posible contactar con nuestros 'ombudpersons'.

Política contra el acoso
_

El objetivo de 'The Programming Historian en español' es ofrecer un entorno abierto en el que la comunidad de participantes sean libres para analizar ideas, realizar preguntas, sugerir cambios, y pedir aclaraciones; también queremos que sea un espacio libre de acoso y hostigamento para todo el mundo con independencia de su género, identidad, orientación sexual, minusvalía, apariencia física, tamaño corporal, raza, edad, religión o conocimientos informáticos. No se tolerará ningún tipo de acoso o ataque *ad hominem*. Los participantes que violen esta regla podrán ser expulsados del proceso editorial a discreción del equipo editorial. Si presencias o sientes que has sido víctima de algún tipo de acoso, por favor, contacta con nuestros 'ombudspersons' (María José Afanador-Llach o Víctor Gayol - http://programminghistorian.org/es/equipo-de-proyecto).

Cómo guiar la conversación

Como editor, todos los participantes del proceso estarán pendientes de tus intervenciones. Para la mayoría de los autores y los revisores será su primera experiencia en un sistema de revisión en abierto como el nuestro. Dado que las publicaciones se realizan en el repositorio de GitHub, es posible que los autores vean los comentarios por parte de los revisores antes que el editor. Por este motivo, hay que dejar claro cómo funciona el proceso y cuándo los participantes deben intervenir o esperar nuevas instrucciones.

Siempre que sea posible se recomienda publicar algún mensaje con el que se haga explícita la recepción de los comentarios. Por ejemplo, tras recibir la primera revisión, publica una respuesta para agradecer al primer revisor y recuerda al autor que una segunda revisión (en el caso de las lecciones nuevas) se encuentra en camino. Por este motivo, sugiere al autor que espere hasta recibir los comentarios pendientes. De esta manera todo el mundo sabe qué pasos hay que seguir.

Si estás muy atareado, simplemente publica una nota en el foro para decir que has visto los nuevos comentario y que necesitarás más tiempo para responder en detalle. Gestionar las expectativas de todas las partes es la mejor manera de asegurarte que el proceso de revisión tenga un final feliz.

Cómo resumir la revisión

Una vez las revisiones necesarias se hayan producido, tu papel consistirá en resumir las sugerencias de cambios y dar al traductor o autor las instrucciones necesarias para que conteste a los comentarios que consideres oportunos. Si algunas de las sugerencias son contrarias al espíritu de The Programming Historian en español, puedes decirle al autor, de manera muy educada, que ignore determinados cambios. En todo momento, ten en cuenta qué significa ser autor, traductor y revisor. Como editor, te interesa que la revisión sea clara, pero al mismo tiempo tienes el derecho de rechazar aquellas ideas que no mejoran el texto. También te interesa asegurarte de que el objetivo de la revisión no se ha visto modificado. Por tanto, un buen resumen de las revisiones ayudará al autor a responder y es una forma de dar por bueno el texto si se llevan a cabo las modificaciones solicitadas por el editor.

Cómo gestionar el proceso de revisión

Junto con tu resumen de las revisiones y las instrucciones finales, hay que recordar al autor que los cambios deben realizarse en cuatro semanas. De esta manera, nos aseguraremos que los textos se publican en su debido tiempo y no se demoran de manera innecesaria. Si el autor considera que no podrá cumplir esta condición, se deberá acordar con el editor una nueva fecha.

Nota sobre la revisión de traducciones

En The Programming Historian en español sabemos que existe un gran abanico de maneras de utilizar nuestro idioma en España y en América Latina. En defensa de la diversidad, hemos considerado que los revisores de las traducciones deben respetar los usos regionales (‘ordenador’, ‘computadora’ o ‘computador’) del traductor, siempre y cuando el texto en general tenga corrección gramatical, claridad y que respete la integridad de las ideas expresadas en la lección original. Esto se debe enfatizar a la hora de dirimir cualquier diferencia entre revisores y traductores.

Aspectos técnicos del proceso de revisión - Lista de verificación

Nuestro proceso de revisión se lleva a cabo en el repositorio de envíos de GitHub. Las instrucciones sobre cómo subir los archivos, el formato de los archivos y el uso de Markdown se encuentran en nuestra Guía para autores y traductores actualizada periódicamente con nuevas instrucciones. Como editor, deberás familiarizarte con los pasos a seguir y referirte a ellos cuando sea necesario. Si necesitas ayuda, siempre puedes escribir a otro editor del equipo.

Desde un punto de vista técnico, estas son las áreas en las que tendrás que intervenir como editor:

A) Dar nombre al archivo

El editor debe sugerir un nombre para el archivo de la traducción o lección nueva conforme a las siguientes pautas:

Una vez hayas escogido el nombre del archivo, utiliza el mismo nombre para crear un directorio nuevo en imágenes; esta nueva carpeta contendrá las imágenes de la lección. Si la lección contiene archivos con datos, haz lo mismo pero en la carpeta assets del repositio GitHub de The Programming Historian en español. Por favor, ten en cuenta que, en el caso de las traducciones donde el traductor no modifica imágenes o datos, estos ya están alojados.

B) Revisar el etiquetado Markdown

Los autores y traductores deben asegurarse de que utilizan Markdown de manera apropiada para dar formato y estructurar el texto. Si han seguido la sintaxis, no debería haber problema. Ahora bien, si puedes ver algún símbolo Markdown en el archivo, quiere decir que algo ha salido mal. Las instrucciones sobre cómo utilizar Markdown se encuentran en nuestra guía para autores y traductores.

Puedes comprobar con facilidad si todo es correcto accediendo a la visualización generada en GitHub: https://github.com/PH-espagnol/borradores/tree/master/lecciones/NOMBRE-DEL-ARCHIVO-AQUÍ (nota: sin extensión .md).

Si la visualización no funciona, hazlo saber a Víctor Gayo (en español), quien trabajará con Matthew Lincoln para diagnosticarlo. Si lo haces en inglés, dirígete directamente con Matthew Lincoln.

C) Comprobar que las imágenes sean correctas

Todas las imágenes deberían utilizar nombres de archivos consistentes y semánticamente claros. Si un texto contiene varias imágenes seguidas, el orden es muy importante (por ejemplo, una serie de capturas de pantalla). En tal caso se puede recomendar nombrar los archivos de manera secuencia; lo ideal sería utilizar el nombre del archivo de la lección (o una versión más corta) seguido de un número que indique su posición. Por ejemplo: contando-frecuencias-1.png, contando-frecuencias-2.png, etc.

En el caso de las lecciones nuevas, si un tutorial ya contiene archivos numerados, hay que tener en cuenta que el orden puede variar durante el proceso de revisión. Antes de publicar la lección, pues, hay que revisar que todos los nombres de los archivos estén actualizados. De esta manera, podremos actualizar los tutoriales con mayor facilidad en el futuro. Gracias por ayudarnos a mantener The Programming Historian en español.

Con independencia de cómo se nombren las imágenes (semánticamente o de manera secuencial), todos los archivos deben situarse en el directorio imagenes. El sub-directorio debe tener como nombre el slug de la lección. Por favor, comprueba que las imágenes tienen un formato adecuado como PNG o JPEG y que el tamaño es correcto (en píxeles y en bytes).

Más información sobre cómo añadir las imágenes en nuestra guía para autores y traductores.

D) Verificar los archivos con datos

Al igual que las imágenes, todos los datos deben almacenarse en nuestro sitio; es decir, por motivos de sostenibilidad, no deben enlazarse como recursos externos. Los archivos de este tipo deben guardarse en la carpeta assets de The Programming Historian en español, siguiendo las mismas reglas que en el apartado anterior. Con todo, los autores pueden proporcionar una descripción para reflejar el contenido del archivo. Por ejemplo:

E) Comprobar vídeos y Gifs

Se recomienda no incluir vídeos o gifs porque provocan muchos problemas. Por ejemplo, resulta muy difícil solicitar cambios en vídeos durante el proceso de revisión porque requiere dedicarle mucho tiempo; además, los vídeos no se pueden editar con tanta facilidad si la lección requiere nuevas actualizaciones. Asimismo, para incorporar vídeos se tendría que mantener un canal en YouTube. Como es lógico, no se pueden imprimir pero gran parte de nuestros lectores utilizan versiones en PDF. Por tanto, solo deberían incluirse en casos totalmente necesarios.

Si un tutorial contiene algún vídeo, éste debe publicarse en un canal de YouTube. El canal de YouTube aún no ha sido configurado por lo que como editor deberías ponerte en contacto con otros miembros del equipo. En nuestro repositorio GitHub se almacenaría una copia de seguridad; el nombre del archivo debe seguir las instrucciones precedentes y guardarse en la carpeta assets:


Aceptación y publicación - Lista de verificación

Una vez el autor y tú como editor estéis satisfechos con el texto, sea una traducción o una lección nueva, el siguiente paso consiste en mover el archivo desde el repositorio de envíos al repositorio principal que aloja nuestro sitio web.

1) Mueve el archivo

La manera más fácil de publicar el texto es utilizar git en tu terminal de línea de comandos. Las siguientes instrucciones presuponen que ya has clonado en tu ordenador los repositorios jekyll y ph-submissions/es (si no es así, nuestra introducción a GitHub puedes ser útil). Si tienes alguna duda puedes contactar con Matthew Lincoln (en inglés) para que te ayude, o en español a través de Víctor Gayol.

  1. Sitúate en el director local de tu repositorio ph-submissions/es.
  2. Introduce git pull para descargar los últimos cambios en tu ordenador (o sync si utilizas GitHub Desktop).
  3. Repite los pasos 1 y 2 para el repositorio local de jekyll en tu máquina.
  4. Copia el texto, los archivos con datos y las imágenes guardados en ph-submissions/es y ponlos en el lugar apropiado del repositorio jekyll de tu ordenador. Si utilizas la línea de comandos, introduce cp; si, por el contrario, usas GitHub Desktop utiliza la interfaz gráfica de usuario para moverte por los directorios y mover los archivos.
  5. Dese tu repositorio local de jekyll, debes introducir git add para añadir los nuevos archivos, y a continuación got commity git push para actualizar los cambios en el repositorio en línea.

Después de haber movido la lección al repositorio local de jekyll tendrás además que guardar la lección que ya enviaste en el repositorio ph-submissions.

  1. Sitúate en el directorio local de tu repositorio ph-submissions/es.
  2. Añade una nueva línea en el encabezado YAML de la lección ya publicada: redirect_from: "/lessons/LESSON-SLUG"
  3. Copia la lección ya publicada de lessons/ a lessons/published/.
  4. Copia el folder de imágenes que contiene las imágenes de la lección ya publicada de images/ a images/published/.
  5. Utiliza git add, git commit, y git push para finalizar todos los cambios.

2) Crea una biografía para el autor

En el caso de las lecciones nuevas, si el tutorial ha sido escrito por un autor con el que no hemos trabajado anteriormente, los editores deben añadir información sobre el autor en la página directorio de autores del repositorio de The programming historian. En el caso de una trducción, debes traducir tambin la biografa incluyendo la clave es. Sigue la sintaxis de los ejemplos ya incluidos:

- name: Jim Clifford
  bio: 
   es: |
       Jim Clifford es profesor ayudante en el Departamento de Historia de la Universidad de Saskatchewan.

Los espacios en blanco son importantes, así que asegúrate de que la identación se ajusta a la de los otros casos y utiliza espacios en blanco en vez de tabuladores.

3) Añade traductor, revisores y editores al archivo YAML

Es muy importante acreditar el trabajo de nuestros traductores, revisores y editores. Así, pues, localiza el bloque YAML que se encuentra al inicio del tutorial, y añade el nombre de los revisores y de todos los miembros de nuestra comunidad que han contribuido durante el proceso de revisión. Además, crea un campo editor y añade tu nombre y de cuantos otros editores hayan contribuido en la publicación. Las instrucciones para dar formato al bloque de YAML se encuentran en la guía para autores y traductores.

Si se trata de una traducción, asegúrate de que se mantienen los datos del YAML original, e introduce un campo para el traductor (translator), otro para los revisores de la traducción (translation-reviewer) y otro más para el editor de la traducción (translation-editor).

Los revisores que no hayan trabajado con nosotros en el pasado también deben añadirse en el archivo reviewers.yml; de esta manera, el nombre de los revisores aparecerá como parte de nuestro equipo. Por favor, no te olvides de este paso.

4) Añade un nivel de dificultad el archivo YAML

Con el objetivo de ayudar a los lectores a evaluar si una lección se ajusta a sus necesidades y experiencia, proporcionamos un campo “Recomendado para usuarios __” en el bloque YAML. Actualmente, contamos con tres niveles de dificultad, que se escogen mediante tres códigos numéricos: 1 (introductorio), 2 (intermedio) y 3 (avanzado). En el caso de las lecciones nuevas, para añadir el nivel de dificultad a la lección, debes incluir las siguientes líneas al archivo YAML:

difficulty: 1

5) Añade un ticket de revisión al archivo YAML

Crea un ticket de revisión en el archivo YAML y proporciona el número del ticket correspondiente al envío del archivo en el repositorio borradores. Este procedimiento se realiza para incrementar la transparencia del proceso de revisión. La información, además, se utilizará para proporcionar un enlace al ticket de revisión.

6) Actualiza la fecha en el archivo YAML

Actualiza la fecha en el campo correspondiente del archivo YAML tomando como referencia el día en que el archivo fue movido al repositorio jekyll, salvo en el caso de las traducciones.

7) Otros aspectos para concluir el YAML de la lección

Teniendo como referencia el ejemplo de abajo, asegúrate que toda la parte preliminar de la lección está completada adecuadamente. Los campos comunes que necesitas escribir o editar en este punto son:

Observa el siguiente ejemplo para apreciar cómo debe verse el encabezado YAML de la lección completo:

---
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
difficulty: 2
activity: analyzing
topics: [distant-reading]
abstract: "En esta lección aprenderás qué es el modelado tópico y por qué podrías querer emplearlo en tu investigación. A continuación, aprenderás a instalar y trabajar con MALLET, que es una herramienta para procesar lenguaje natural."
---

8) Busca una imagen que represente la lección

Las lecciones se representan mediante una imagen vintage que refleja algún elemento de las tareas descritas en el tutorial. Puedes ver todas las imágenes en el índice principal de lecciones. El editor es el encargado de seleccionar las imágenes.

Puedes buscar imágenes en los recursos siguientes:

Si como editor estás buscando una imagen para una lección nueva, asegúrate de que la imagen sigue el mismo estilo que las imágenes anteriores; debería ser una ilustración, no una fotografía, tener al menos 200 píxeles de anchura y altura, y estar libre de derechos. Asegúrate de que la magen no es ofensiva y ten en cuenta nuestro compromiso con la diversidad; en otras palabras, intenta encontrar una imagen que no perpetúe estereotipos o envíe mensajes sutiles sobre la masculinidad y la raza blanca.

Antes de editar la imagen, guarda el archivo original. El nombre del archivo debe coincidir con el slug de la URL de la lección y, además, -original; el formato del archivo debe ser .png. Por ejemplo, la lección “Cleaning Data with OpenRefine” tiene el slug cleaning-data-with-openrefine; por tanto, el nombre de la imagen original debería ser cleaning-data-with-openrefine-original.png.

A continuación, crea una copia de la imagen, córtala en un cuadrado sin eliminar detalles relevantes, cambia la dimensión a 200x200 píxeles y convierte la imagen a escala de grises. Puedes hacer cuanto retoques creas necesarios a fin de que se asemeje al resto de imágenes, por ejemplo, modficiar la luz o alterar el contraste. Guarda esta nueva imagen con el slug de la lección. Siguiendo con el ejemplo ya dado, la nueva imagen debería llamarse cleaning-data-with-openrefine.png.

Sube la imagen original al directorio gallery/originals y la imagen editada al directorio gallery.

9) Incorpora tu lección en nuestro Twitter bot

Adicionalmente a la promoción vía Twitter descrita abajo, también utilizamos un Twitter bot para volver a promocionar lecciones pasadas. Para añadir la lección nueva a nuestro pipeline deberás añadirla como una fila en esta hoja de cálculo. Todos los miembros del equipo editorial deben poder hacer cambios; envía un correo electrónico al grupo de google si tienes algún problema. Deberás insertar una nueva fila para tu lección al final de la tabla con los siguientes campos:

message_one (columna A) - un mensaje de twitter para circular al comienzo de la semana.
message_two (columna B) - un mensaje de twitter “En caso de que te lo hayas perdido” para circular ms tarde en la semana.
link (columna C) - el enlace a la lección.

Deja la columna D en blanco y sin tocar - este campo es utilizado por el Twitter bot para registrar su progreso en la lista. Ten en cuenta además que este paso no reemplaza tu propia promoción de la lección. El bot escoge las lecciones aleatoriamente, una cada la semana, así que pueden pasar meses hasta que tu lección aparezca por este medio.

10) Confirma que todos los enlaces y encabezados YAML funcionen correctamente

Una vez que envíes tus cambios a la rama gh-pages del repositorio de programminghistorian, el sitio será comprobado automáticamente por Travis CI (Continuous Integration). Este proceso comprueba dos cosas: primero, que todo el código de YAML y markdown sea compilable y, segundo, que todos los hipervínculos del sitio apunten a páginas válidas y en operación.

Ejecutamos estas compilaciones principalmente para comprobar que las URL que alguna vez funcionaron siguen funcionando, ya que muchas veces las páginas web externas se mueven a nuevas direcciones o ya no están en línea. También son una excelente manera de detectar errores tipográficos pequeños que pueden haber pasado por alto autores, editores y revisores. El estado de estas pruebas (a menudo llamado “Estado de compilación” (“Build Status”) en Travis CI y en GitHub) se puede ver navegando a la página del repositorio php_repo- sitory y haciendo clic en “Commits” en la parte superior izquierda del menú de código.

GitHub commit menu location

Esto te mostrará la lista de cada cambio realizado en el repositorio principal, junto con un icono de estado:

En caso de error, debes consultar la bitácora de compilación (Build logs) para saber qué es lo que lo causa.

  1. Haz clic en la X roja de la más reciente modificación (la que está más cerca de la parte de arriba de la página), y haz clic en el vínculo “Details”. Travis details location
  2. Esto te llevará a la página de la bitácora de compilación en Travis CI. Las bitácoras de compilación contienen generalmente cientos de líneas, pero la información sobre el error que estamos buscando estará al final. Haz clic en el pequeño círculo gris de la parte superior derecha para desplazarte hacia abajo. The top of the Travis CI build screen
  3. Verás dos tipos de errores: primero, si la página carece de un campo YAML (i.e. si la lección no tiene el campo editors) el error estará marcado en rojo. Los errores en los vínculos externos también se enlistan en rojo, agrupados por la página en la que aparecen. Si algún vínculo en tu nueva lección causa error, regresa y confirma que no hay errores de escritura. Si los hay, haz las correcciones necesarias, envía las modificaciones al repositorio y espera a que Travis CI corra las pruebas de nuevo. Locating error details in Travis CI build results

11) Da las gracias a todo el mundo y difunde el tutorial

Es importante enviar un correo electrónico o un mensaje a todos los participantes para agradecerles el esfuerzo. En particular, da las gracias al autor o al traductor por enviar su texto y anímalo a volver a trabajar con nostros en el futuro. También puedes proporcionarle alguna idea sobre cómo difundir y anunciar su contribución. Las lecciones más visitadas suelen contar con la promoción del autor. Por ejemplo, el autor podría realizar las siguientes acciones:

¡Por favor, no abandones la lección a su suerte! Ya hemos realizado el trabajo, así que asegurémosnos que ha valido la pena.