Guía para revisores

Esta guía pretende responder preguntas frecuentes y ayudar a los revisores a comprender mejor su rol durante el proceso editorial.

{% include toc.html %}

Nuestra filosofía

Para el equipo de The Programming Historian en español revisar una traducción o una lección nueva constituye una oportunidad para aprender una nueva habilidad (a cualquier nivel) y para contribuir en la comunidad de humanidades digitales al mismo tiempo. Por eso nos esforzarmos en que nuestros revisores reciban crédito y reconocimiento por su trabajo.

Política antiacoso

Queremos exponer los principios que rigen The Programming Historian en español, así como toda la correspondencia accesible en nuestros fórums entre los revisores, los autores, los editores y otros colaboradores.

The Programming Historian en español tiene como objetivo ofrecer, por un lado, un entorno abierto a la comunidad en el que reine la libertad para analizar ideas, hacer preguntas, sugerir cambios o pedir aclaraciones. Por el otro, quiere ser un espacio libre de acoso y violencia hacia cualquiera de los participantes con independencia de su género, identidad, orientación sexual, capacidades, físico, raza, edad, religión o nivel de conocimiento. No toleraremos ningún tipo de acoso, humillación o ataque personal por parte de los colaboradores. Quien, a discreción del equipo editorial, viole este principio será expulsado del proyecto. Si alguna de las partes es testigo o considera que ha sido víctima de un abuso, se recomienda contactar a uno de nuestros mediadores (Antonio Rojas, Víctor Gayol o Maria José Afanador-Llach).

¡Gracias por ayudarnos a crear un espacio seguro para todos y todas!

Colaboración, no juicio

Nuestro proceso de revisión es un poco distinto del considerado "tradicional". No solicitamos una revisión para juzgar si un tutorial es suficientemente "bueno"; por el contrario, creemos que los revisores juegan un papel fundamental para crear recursos de manera colaborativa, productiva y sostenible. Cuando una traducción o un tutorial entra en nuestro flujo de trabajo, nuestro objetivo es hacer todo lo posible para que los recursos sean útiles y se publiquen en un tiempo razonable.

Críticas constructivas

Revisar una traducción o una lección nueva no consiste únicamente en evaluar los méritos y defectos (aunque esto también es importante, claro), o en decidir si la propuesta es adecuada para The Programming Historian en español. Nuestro objetivo es mejorar el tutorial proponiendo ideas procedentes de un lector externo. Por eso queremos que nuestros revisores proporcionen comentarios tal y como lo harían con un artículo escrito por un colega, es decir, que proporcionen una crítica justa y constructiva que ayude al autor (o traductor) a mejorar su trabajo teniendo en cuenta una audiencia amplia. No solicitamos la revisión de material que no sea publicable de primeras; sin embargo, creemos que las contribuciones de los revisores mejoran de manera significativa las traducciones y lecciones nuevas.

Transparencia

Queremos que el proceso de producción y revisión sea transparente. Por eso tiene lugar en nuestro repositorio Github. En concreto, usamos Github para comentar, así como su sistema de seguimiento de incidentes, ya que permite encontrar de manera precisa las sugerencias y debatir las ideas con los autores y revisores. Nos permite, además, evitar que nuestras conversaciones se pierdan en la bandeja del correo. Por último, los colaboradores y usuarios pueden recuperar conversaciones antiguas que han cobrado relevancia nuevamente.

Tu trabajo como revisor --así como tu identidad-- será totalmente visible para el autor o traductor. En consecuencia, los comentarios deben dirigirse directamente al autor o traductor (y no al editor). Si en algún momento del proceso tienes dudas sobre cuál es tu rol o qué se espera de ti, por favor, publica tus dudas o preguntas en nuestro repositorio para que alguno de nuestros editores pueda ayudarte. En ocasiones podemos demorarnos un poco pero estamos convencidos de que, una vez se publique la traducción o lección, habrá valido la pena esperar unos días.

A fin de mantener nuestro compromiso con una investigación pública, abierta y transparente, te animamos a mantener las conversaciones en Github, tal y como se expone en el apartado dedicado a nuestro flujo de trabajo. Sin embargo, también queremos que todo el mundo se sienta cómodo y por eso, pero de manera ocasional, también aceptamos tratar un asunto en privado. En tal caso puedes contactar a tu editor asignado o a alguno de nuestros ombudsperson Maria José Afanador-Llach.

A menos que nos indiques lo contario, tu nombre aparecerá como revisor en la página de la lección en The Programming Historian en español una vez se publique de manera oficial. Esto es solo un pequeño reconocimiento pero nos gustaría enfatizar que The Programming Historian en español se lleva a cabo gracias al trabajo de los voluntarios y por eso es obligado darles crédito.

¿Qué revisar?

El estilo informal de The Programming Historian en español puede dar la impresión de que las lecciones son fáciles de traducir o escribir. En realidad, traducir o escribir un buen tutorial exige un esfuerzo tan grande (o mayor) como el necesario para crear un artículo académico.

A continuación, destacamos una serie de cuestiones que como revisor deberías tener en cuenta. Algunas serán más relevantes que otras en función del tema, el público objetivo o la dificultad del tutorial. No se trata de una lista exhaustiva y tampoco pedimos que los revisores respondan a cada una de las cuestiones sino que nos proporcionen una orientación general.

Destinatario

Si has ojeado algunos de los tutoriales de The Programming Historian en español, te habrás dado cuenta de que no tenemos un destinatario estándar para todas las lecciones. Algunos tutoriales son para principiantes, otros requieren conocimientos técnicos, e incluso algunos están dirigidos a usuarios experimentados que necesitan resolver un problema muy específico. ¡Nos gusta la variedad!

Aunque cada lección mantenga el estilo de su autor (o traductor), queremos que todas las lecciones sean legibles y estén escritas en un registro homogéneo.

Traducciones

De manera más específica, en cuanto a las traducciones, apreciamos el rigor pero también somos conscientes de que la literalidad no se puede alcanzar si se persigue una lectura amena. Además, en ocasiones los traductores deben añadir aclaraciones culturales a través de notas o entre paréntesis. También hay que considerar que los traductores utilizan variantes regionales para referirse a ciertas cosas ('ordenador, 'computadora', 'computador'), que es conveniente respetar. He aquí, pues, algunas cuestiones a tener en cuenta:

• ¿El lenguaje (léxico, sintaxis, ortografía) es adecuado?
• ¿Se traducen todos los tecnicismos al español?
• ¿Los tecnicismos dudosos van acompañados del original inglés entre paréntesis?
• Si no se traducen ciertos términos, ¿se marcan en cursiva?
• ¿El traductor ha añadido notas aclaratorias?
• ¿Las capturas de pantalla y trozos de código han sido adaptados?
• ¿Se han añadido referencias bibliográficas en español?

Puesto que muchos de lo tecnicismos son nuevos y/o todavía no están recogidos en los diccionarios, recomendamos el uso de la Taxonomía sobre Actividades de investigación digital en humanidades de TaDiRAH y el Glosario de Preservación Archivística Digital (Versión 4.0) de Voutssas-M y Barnard Amozorrutia (UNAM).

Lecciones nuevas

Por lo que respecta a las lecciones nuevas, queremos que las explicaciones técnicas (y el nivel de dificultad) sea constante a lo largo del tutorial. En tanto que revisor, queremos que, en un tutorial dirigido a un usuario experimentado, seas capaz de detectar pasajes que explican en detalle un concepto demasiado simple. Y a la inversa: queremos evitar tutoriales dirigidos a principiantees que no explican de manera adecuada un concepto fundamental para entender la lección. Aspectos a tener en cuenta:

• ¿El autor tiene en mente un destinatario ideal a lo largo de la lección?
• ¿Hay pasos explicados en exceso? ¿Hay otros pasos, en cambio, que requieren mayor detalles?
• ¿Existe otra lección en The Programming Historian en español que tenga un destinatario semejante? ¿En qué sentido la lección supone una novedad?

Preliminares

• ¿Qué programas o lenguajes son necesarios?
• ¿Qué habilidades se necesita conocer previamente?
• ¿Qué experiencia previa se necesita?
• ¿Qué datos se necesitan? ¿Son accesibles?

Estructura

• ¿Los objetivos y las habilidades previas que se necesitan se exponen de manera clara al inicio del tutorial?
• ¿Las habilidades derivadas del tutorial son útiles?
• ¿Las capturas de pantalla y diagramas ilustran los pasos más importantes del tutorial?
• ¿Las secciones y títulos de sección son claros y guían al lector?

Beneficios

• ¿Se explica de manera clara por qué la herramienta o los métodos son útiles para investigar?
• ¿Se sugiere cómo los conceptos (o un paso concreto) se pueden aplicar a otros casos concretos?

Flujo de trabajo

• Si la lección tiene una extensión larga, ¿debería dividirse en otras más breves?
• ¿Hay recapitulaciones, resúmenes o paradas que marcan una transición a lo largo del tutorial?
• Si se requiere un dataset, ¿está disponible en internet para descargar?

Sostenibilidad

Para aumentar la vida útil de nuestras lecciones, los revisores deben tener en cuenta las siguientes preguntas acerca de la sostenibilidad. Cada propuesta es diferente, por lo que algunas de estas recomendaciones no son pertinentes. Teniendo en cuenta el nivel de dificultad de la lección y su público objetivo, los revisores deben utilizar estas preguntas como guía para asegurar que los tutoriales son lo más sostenibles posibles desde el momento en que se publican.

• ¿Se listan las versiones y especificaciones de los programas utilizados? ¿Los recursos utilizados son los más recientes? Si la lección usa versiones más antiguas, ¿el autor lo justifica?
• ¿La metodología o herramientas utilizadas en la lección están a la orden del día? ¿Están actualizadas?
• ¿Qué fuentes o datos se utilizan? ¿Están incluidos de tal manera que no dependan de un alojamiento externo?
• ¿Qué enlaces externos contiene la lección? ¿Estos recursos son actuales o existen otros, más recientes o apropiados, que se podrían vincular?

Integrando la lección a The Programming Historian en español

• ¿La lección contribuye al desarrollo de otras lecciones ya publicadas?
• ¿Existen enlaces adecuados que conectan la lección con otras semejantes o complementarias?

Cómo enviar tu revisión

Gestionamos todo el proceso de revisión, tanto de traducciones como de lecciones nuevas, a través de GitHub. Cuando una traducción o una lección nueva esté lista para ser revisada, un miembro del equipo editorial te facilitará un enlace para que puedas leerlo y un enlace al repositorio en donde podrás publicar tus comentarios. Las conversaciones tienen lugar en GitHub, un entorno gratuito y social, por lo que tendrás que registrate con una cuenta propia para publicar tus comentarios. Te animamos a mantener todas las conversaciones en Github pero ocasionalmente puedes enviar un correo electónico al editor si necesitas comunicarle algo en privado.