¡Haz una donación a Programming Historian!

Guía para autores

Una mujer escribiendo en un escritorio.

Paso 1: Proponer una nueva lección

Paso 2: Escribir y dar formato a una nueva lección

Paso 3: Enviar una nueva lección

Estas directrices han sido desarrolladas para ayudarte a entender el proceso de creación de un tutorial para Programming Historian en Español. Incluyen detalles prácticos sobre el proceso de redacción de un tutorial, así como indicaciones sobre el flujo de trabajo y el proceso de revisión entre pares. Si en algún momento hay algo que no te queda claro, por favor envía un correo electrónico a Riva Quiroga.

Paso 1: Proponer una nueva lección

Aceptamos tutoriales relevantes para las humanidades, dirigidos a cualquier nivel de aptitud técnica y experiencia, que se centren en un problema o proceso, que puedan ser sostenibles a largo plazo y que estén dirigidos a una audiencia global. El alcance y la longitud del tutorial han de corresponderse con la complejidad de la tarea que se enseña. Los tutoriales no deben exceder las 8.000 palabras (incluyendo el código) sin el permiso explícito del editor, el que se otorgará únicamente en circunstancias excepcionales. Esperamos que la mayoría de las lecciones tengan entre 4.000 y 6.000 palabras. Si resulta pertinente, puede que solicitemos dividir en varios tutoriales las lecciones más largas.

Si tienes una idea para una nueva lección, completa el formulario de propuestas y envíalo a Riva Quiroga.

Para tener una idea de lo que publicamos, consulta nuestras lecciones ya publicadas, lee nuestra guía para revisores o explora las lecciones actualmente en desarrollo. Animamos el envío de propuestas de lecciones sobre temas ya cubiertos o en desarrollo, siempre que la lección nueva haga una contribución propia.

A fin de que nuestras lecciones sean sostenibles a largo plazo, se sugiere proponer tutoriales que no dependan de un programa o de una interfaz específica que no haya demostrado ser estable en el tiempo. De lo contrario, los tutoriales necesitarían cambios con cada actualización. En aras de una mayor conservación, es mejor enseñar conceptos que a ‘hacer clic sobre un botón X’. Asimismo, se espera que los tutoriales no se centren en documentar cómo utilizar un determinado programa/aplicación/interfaz, sino que muestren cómo abordar un caso de estudio propio de las humanidades a través de esa(s) herramienta(s).

Tras la aprobación de tu propuesta, crearemos una página en el sitio de envíos con el título provisional y los objetivos de la lección. Esto sirve para documentar el progreso realizado durante la escritura de la lección. Para asegurar la publicación oportuna, te pedimos que entregues tu texto al cabo de 90 días tras la aprobación. Durante este período de 90 días, tu punto de contacto será la jefe de redacción o el editor o editora que se haya asignado para acompañarte durante el proceso.

Paso 2: Escribir y formatear el tutorial

Esta guía de estilo define un conjunto de normas para ser utilizadas al crear lecciones en español para Programming Historian. Al seguir estos lineamientos nos ayudas a asegurar que el contenido sea consistente y accesible.

La guía contempla tres secciones, que deben ser leídas antes y después de la escritura:

A. Estilo y audiencia

Esta primera sección se ocupa de cuestiones de estilo generales que te ayudarán a tomar decisiones que satisfagan las necesidades de nuestra audiencia y editores. Incluimos información básica sobre el estilo y el tono, el acceso abierto y los valores del código abierto, información sobre la escritura para una audiencia global, la escritura sostenible y la toma de decisiones inteligentes sobre los datos utilizados en las lecciones. Lee esta sección cuando planifiques tu lección y vuelve a leerla antes de enviarla para asegurarte de que el tutorial cumple con estos requisitos.

Lenguaje y estilo

Código abierto, acceso abierto

Programming Historian está comprometido con los valores del código abierto. Todas las lecciones deben usar lenguajes de programación y software de código abierto siempre que sea posible. Esta política tiene por objeto reducir al mínimo los costos para todas las partes y permitir el mayor nivel de participación posible.

Una vez aprobada tu lección, aceptas que se publique bajo licencia Creative Commons “CC-BY”.

Escribe para una audiencia global

Programming Historian es leído por personas que viven en todo el mundo. Es por ello que debes tomar medidas para que tu lección sea accesible para el mayor número de personas posible. Las siguientes directrices te ayudarán a enfrentar una audiencia global:

Escritura sostenible

Programming Historian publica lecciones pensando en el largo plazo. Por favor, sigue estas directrices sobre sostenibilidad cuando escribas:

Consulta nuestra política de retirada de lecciones para información sobre cómo el equipo editorial maneja las lecciones que se han vuelto obsoletas.

B. Pautas específicas de escritura

En esta segunda sección se abordan cuestiones más específicas del estilo de escritura, como qué palabras utilizar, cómo usar la puntuación o qué formato utilizar para fechas y números. Lee esta sección antes y después de escribir tu borrador.

Fechas y hora

Números

Encabezados

Los encabezados no deben contener código en línea o un formato de estilo como negrita, cursiva o de código. Los encabezados siempre deben preceder inmediatamente al texto del cuerpo. No pongas después de un encabezado una advertencia u otro encabezamiento sin un texto introductorio o descriptivo.

Listas

Típicamente, usamos listas numeradas y listas con viñetas. Los elementos de la lista comienzan con mayúscula. Los elementos de la lista deben ser tratados como elementos separados y no deben ser encadenados con puntuación o conjunciones.

Sin estilo apropiado:

Con estilo:

Puntuación

Mayúsculas

La pauta es usarlas con moderación en la prosa corriente. Reglas específicas:

Casos especiales y otros elementos a tener en cuenta

Referencias

Lenguaje inclusivo y no discriminatorio

En Programming Historian nos comprometemos a publicar tutoriales que no reproduzcan lenguaje sexista y discriminador. Te pedimos que tengas en cuenta las siguientes recomendaciones:

C. Guía de formato

Esta última sección abarca cuestiones de formato para el envío de tu lección. Lee esta sección antes y después de escribir tu borrador. Si te equivocas en alguno de estos elementos, podrás corregirlo cuando publiquemos un avance en línea de tu lección al comienzo del proceso de revisión de pares.

Escribe en Markdown

Todas las lecciones deben ser escritas en Markdown. Se ha proporcionado una plantilla para escribir las lecciones.

Markdown es un lenguaje de marcado que se crea mejor con un editor de texto. MS Word y Open Office NO son editores de texto y deben ser evitados. Recomendamos Atom, TextWrangler, TextEdit, MacDown, Notepad++ o Sublime Text. Para una introducción sencilla a Markdown puedes ver la lección Introducción a Markdown o la referencia concisa GitHub Guide to Markdown.

Tu lección debe ser guardada en formato .md. El nombre del archivo de tu lección se convierte en parte de la URL de la lección, por lo tanto, debe ser nombrado de acuerdo a las siguientes reglas:

Negrita, cursiva y subrayado

Para asegurar la consistencia de las lecciones, sigue las siguientes directrices de formato de texto:

Negrita

Cursiva

Subrayado

Alertas y advertencias

Si quieres incluir un aparte o una advertencia, puedes utilizar el siguiente bloque de código:

<div class="alert alert-warning">
¡Asegúrate se seguir cuidadosamente las instrucciones!
</div>

Figuras e imágenes

Las imágenes pueden ayudar a tu audiencia a entender los pasos de la lección, pero no deben ser usadas como decoración. Si deseas utilizar imágenes en tu lección, etiquétalas secuencialmente siguiendo el patrón: nombre-leccion1.jpg, nombre.leccion2.jpg, etc. Refiérete a ellas en el texto como “Figura 1”, “Figura 2” y así sucesivamente. Todas las figuras deben venir con una leyenda concisa y notas finales cuando sea apropiado. Debes tener el derecho legal para publicar cualquier imagen que incluyas en tu lección.

Utiliza formatos de archivos amigables para la web, como .png o .jpg, y reduce las imágenes grandes a un máximo de 840 px en el lado más largo. Esto es importante para lectores en países con velocidades de Internet más lentas.

Las imágenes deben guardarse en una carpeta con el mismo nombre que el archivo .md de la lección.

Para insertar una imagen en tu texto, utiliza el siguiente formato:

{% include figure.html filename="NOMBRE-ARCHIVO-IMAGEN" caption="PIE DE FOTO UTILIZANDO \"ESCAPED\" QUOTES" %}

Ten en cuenta que las comillas internas en el pie de foto deben escaparse con una barra invertida, como en el ejemplo anterior. Es posible que las imágenes no aparezcan en las vistas previas de la lección, pero tu editor/a se asegurará de que se reproduzcan correctamente cuando esta se publique.

Ejemplos de código

Las líneas de código deben tener un formato que las distinga claramente de la prosa:

El bloque de código se verá así

` y así` el código dentro del texto.

Sigue las mejores prácticas para escribir tu código:

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 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, ... y ..1, ..2, etc.

Paso 3: Enviando una nueva lección

Una vez que tu archivo ha sido preparado de acuerdo con las especificaciones anteriores, ¡ya puedes enviárnoslo! Te sugerimos, de todos modos, que pidas al menos a dos personas que prueben tu lección y te den su opinión. Es muy importante que pruebes que es posible seguir el tutorial desde distintos sistemas operativos sin problema. Esto permitirá al equipo editorial centrarse en que produzcas una lección lo más sólida posible.

Ahora estás listo para enviar la lección a revisión. Los envíos se realizan enviando los materiales por correo electrónico a tu editor o editora para que puedan subirlos a nuestro repositorio de revisión por pares en Github. Sigue estos pasos:

  1. Obtener acceso: crea una cuenta gratuita en GitHub aquí. Solo se necesitan 30 segundos. Envía por correo electrónico tu nombre de usuario/a de Github a tu editor/a, quien le dará acceso a nuestro repositorio. Indícale también el nombre del archivo de la lección y si tiene imágenes o archivos de datos que acompañen al tutorial. Tú no realizarás la carga inicial en GitHub, pero necesitarás acceso para publicar revisiones posteriores.
  2. Prepara los materiales: si tu lección incluye imágenes, asegúrate que todos los archivos están nombrados según las convenciones explicadas más arriba. Las imágenes debes enviarlas en una sola carpeta comprimida. Si tu lección incluye archivos de datos, estos deben ser enviados en otra carpeta comprimida.
  3. Envía un correo electrónico a tu editor/a: hazle saber a tu editor/a que tienes todo listo para el envío de tu lección. Este correo electrónico debe incluir el archivo markdown (.md) de la lección y las carpetas comprimidas con las imágenes y datos, si corresponde.
  4. Únete a la conversación: quien edita la lección subirá los archivos a nuestro repositorio de envíos y hará algunos cambios iniciales para asegurarse de que todo funciona bien. Además, abrirá un “ticket de revisión” para tu lección en la sección de issues de ese repositorio.
  5. Realiza las revisiones: si bien la carga inicial de tu lección en el repositorio ph-submissions será realizada por tu editor/a, el proceso editorial requerirá que hagas modificaciones. Todas las ediciones posteriores deben ser hechas directamente por ti en ese repositorio para asegurarnos de que estás trabajando en la última versión del archivo.

El proceso de revisión de pares

Tu editor/a comprobará que tus archivos se hayan cargado y formateado correctamente. En esta etapa se te enviará un enlace de vista previa donde se evidenciará cualquier error de formato para que puedas corregirlo. Las modificaciones debes hacerlas en el archivo .md de tu lección, que se encuentra en el repositorio de propuesta de lecciones.

La revisión de pares se registrará en un “ticket” de GitHub, que actúa como una discusión abierta en el tablero de mensajes. Ten en cuenta que nuestra revisión de pares se realiza en público y se mantiene a disposición del público como un registro permanente del proceso editorial. Si tienes alguna preocupación o deseas solicitar una revisión cerrada, ponte en contacto con tu editor/a.

El proceso de revisión por pares normalmente se realiza en tres etapas:

1) Tu editor/a leerá y probará cuidadosamente tu lección, proporcionando una primera ronda de retroalimentación a la que se te pedirá que respondas. El propósito de esta primera ronda de retroalimentación es asegurarse de que tu lección responde a las necesidades de la audiencia de Programming Historian y de que los revisores externos reciban una lección que funcione. Normalmente se te dará un mes para responder a esta primera revisión.

2) Tu editor/a abrirá la lección para una revisión formal de pares. Esto incluirá al menos dos revisores que serán contactados por tu editor/a. La revisión también puede incluir comentarios de la comunidad más amplia, que son bienvenidos para contribuir con sus puntos de vista. Por lo general, tratamos de pedir a los revisores que aporten sus comentarios en el plazo de un mes, pero a veces circunstancias imprevistas hacen que esto no sea posible. Tu editor debe dejarte claro que no debes responder a las sugerencias de cambios hasta después de que se hayan publicado ambas y que el editor haya resumido y dado instrucciones claras para seguir adelante. En algunos casos esto puede ser una sugerencia para revisar sustancialmente o repensar la lección. En otros casos será cuestión de hacer algunos cambios menores. En función de los comentarios de la revisión de pares y de la naturaleza de las cuestiones planteadas, puede ser necesario revisar el tutorial más de una vez. En todo momento tu editor se esforzará porque tengas claros los pasos necesarios para que la lección sea publicable. Siempre tendrás la opción de retirarte del proceso de revisión si así lo deseas.

3) Una vez que editor/a y revisores estén conformes con el texto, tu editor/a recomendará la publicación a la jefa de redacción, quien leerá el tutorial para asegurarse de que cumpla con los lineamientos y estándares de esta Guía. En algunos casos, esta etapa puede considerar revisiones adicionales o edición de estilo para que el artículo se ajuste a nuestras normas de publicación. Si la jefa de redacción está satisfecha con tu lección, esta será trasladada al repositorio que aloja el sitio web de Programming Historian para su publicación. Tu editor/a te informará de cualquier información adicional que se requiera en esta etapa (por ejemplo, cómo quieres que aparezca tu nombre y afiliación institucional en la lección).

Puede resultarte útil leer nuestra Guía para editores, donde se detalla nuestro proceso editorial.

Si en algún momento no tienes seguridad sobre cuál es tu papel en ese momento o de lo que debes hacer a continuación, publica una pregunta en el ticket de revisión de tu lección. Nuestro equipo editorial responderá lo antes posible. Nos esforzamos por responder a todas las preguntas en unos pocos días.

¿Qué ocurre una vez que tu lección ha sido publicada?

Ocasionalmente recibimos feedback de personas que se han encontrado con algún error al tratar de completar alguna de nuestras lecciones. En estos casos, nuestra Asistente Editorial abrirá un Issue en GitHub y hará una evaluación para determinar si el error reportado surgió por alguna acción del usuario/a (por ejemplo, al editar el código o cambiar el set de datos utilizado) o por un problema de la lección. Si ocurriese esto último, nuestra Asistente Editorial volverá a testear las secciones de la lección que corresponda y buscará una posible solución. Como parte de este proceso de mantención de las lección, es posible que te contactemos para solicitar tu ayuda o sugerencias. En caso de que no se encuentre forma de resolver el problema, agregaremos una advertencia a la lección indicando que algunas personas han encontrado un error y, cuando sea posible, incluiremos en ese mensaje algunos enlaces que permitan a lectores y lectoras explorar una solución por su cuenta.

Haznos responsables

Nuestro equipo voluntario trabaja duro para proporcionar a autores y autoras una revisión entre pares rigurosa, colegiada y eficiente. Sin embargo, reconocemos que hay momentos en que las expectativas pueden no cumplirse. Queremos que quienes participan en este proceso se sientan con el poder de exigirnos altos estándares. Si, por cualquier razón, sientes que has sido tratado/a injustamente, que el proceso te parece confuso, que la revisión se ha retrasado innecesariamente, que un revisor ha sido grosero, que tu editor/a no ha sido lo suficientemente receptivo/a o tienes cualquier otra inquietud, por favor, déjanos saber para que podamos abordarlo de manera proactiva.

Plantear una preocupación NO afectará negativamente el resultado de tu revisión de pares, incluso si se trata de una revisión de pares en curso.

Para plantear una preocupación, por favor contacta a una de las siguientes personas, según te resulte más cómodo:

Esperamos que no te encuentres en una situación incómoda, pero si esto sucede, te agradecemos que nos ayudes a mejorar.


La versión en inglés de esta guía de estilo fue creada con el apoyo de la Escuela de Humanidades de la Universidad de Hertfordshire. Esta traducción y adaptación al español es producto del trabajo conjunto del Equipo Editorial de Programming Historian en español.