El objetivo de este posteo es proveer una mapa de ruta señalando los recursos disponibles para generar tu propio tutorial.

Hola

El año pasado ayude a pasar algunos cursos del formato de cursos de DataCamp al del framework generado especialmente por Ines Montani. Aquí encontrarás algunos ejemplos de tutoriales creados con este framework.

Luego de un año atareado que incluyo terminar mi doctorado, finalmente tuve cierto tiempo para realizar una contribución a la comunidad sobre como generar estos tutoriales.

¿Por qué usar este framework para armar tu tutorial?

1- Ted Laderas describió algunos “pros y contras” de usar este framework en un post que salió en el blog de RStudio education explicando la diferencia entre el framework de Ines y los tutoriales que pueden generarse con el paquete de R learnr.

2 - La documentación de Ines Montani es realmente detallada. Si encuentran algun problema en mientras estan generando el tutorial les recomiendo fuertemente que vuelvan a consultar su repositorio.

¿Enseñas algún curso de R y queres convertirlo a un tutorial interactivo? Pensá que un curso diseñado para enseñarse con modalidad presencial no es esxactamente lo mismo que un tutorial online Te recomiendo leer este capítulo del libro Teaching Tech Together de Greg Wilson.

Receta para un tutorial interactivo 📝

1. Ingredientes

Primero tenes que dividir tu material en capítulos. Por lo general en un tutorial hay entre 4 y 5 capítulos.

Los capítulos pueden tener:
  • Filminas con texto asociado

  • Ejercicios en bloques de código

  • Ejercicios de opción múltiple

🤖

Podes usar el paquete decampr para generar alguna de las estructuras de archivos básicas.

2. Copia el repositorio 🏁

Primero debes generar una cuenta en GitHub (es gratis). Si no sabes como hacer esto, poer favor revisa esta página. Por consultas sobre el uso de git y GitHub con R te recomiendo consultar el libro Happy git with R de Jenny Bryan.

El repositorio inicial para armar el curso se encuentra en GitHub. Podes obtener una copia usándolo como un template.

Es buena idea mirar la estrutura del repositorio. En este ejemplo es un tutorial de Python, pero es basicamente la misma estructura.

Recorda que el framework de Ines Montani esta también disponible para Python.

3. Elementos a modificar 📦

Filminas con texto
  • 📁 Carpeta slides
    • Las filminas son archivos markdown (.md) files. Es buena idea elegit un nombre claro, por ejemplo que refleje el numero de capítulo y orden en que aparece, por ejemplo chapter2_01.md.

    • How is the structure of the slides file? Ines described it here

Ejercicios en bloque de código
  • 📁 Carpeta exercises
    • Cada archivo de ejercicios tiene asociado otro con las soluciones (e idealmente un archivo para los tests)
    • Los tests de los ejercicios no han sido completamente desarrollados aún.
    • Los nombres de los archivos deben presentar el mismo número como referencia:
Las soluciones y los ejercicios son archivos separados, unidos por el número que se encuentra al final del nombre del archivo
Ejercicios de opciones múltiples
  • 📁 Carpeta chapters
    • No hay archivos especificos para ellos, se generan dentro de cada archivo en el capitulo correspondiente.
    • Podes leer más sobre ellos en la documentación

⚠️

Recordá usar un id para cada ejercicio de opciones múltiples si tenes más de uno dentro del mismo ejercicio. Tenés un ejemplo acá, en el segundo ejercicio

Capítulos
  • 📁 Carpeta chapters
    • Cada capítulo es un archivo markdown (.md).
    • Estructura del capítulo: deberías incluir un nombre para las filminas y archivos de ejercicios y soluciones.
    Ejemplo de la estructura de los capítulos del tutorial de Noam Ross

No olvidar 😮

⚠️ > Recordar incluir un logo en formato .svg! Podes convertir un archivo .png o .jpg a este formato online

3. ¡Cocinando!🍳

¿Incluiste todos tus archivos en el repositorio? ¡Ahora es el momento de ver si todo funciona! Recorda leer la sección: Setting up Binder y modificar el archivo install.R agregando todos los paquetes utilizados en el tutorial -> 📁 Carpeta binder

Deberá usar Binder en su repositorio. ¡Esto puede tomar un tiempo! ⏰

Mientras tanto podes abrirte una cuenta en Netlify para el deploy. Este paso puede ser evitado. ¿Por qué usar Netlify? Encontré este blog post de Yihui Xiecon una posible explicación. ¡Es tu desición!

A partir de que comiences a usar Netlify podrás visualizar los cambios que vas haciendo en el tutorial. El código de los ejercicios no funcionará hasta que no uses Binder en tu repositorio.

4. Personalizalo 🍒

Licencia Creative Commons
Esta obra está bajo una Licencia Creative Commons Atribución-CompartirIgual 4.0 Internacional.

5. Algo falta

⚠️ Recordá que los tests no estan desarrolados. Podés leer la última sección de la documentación para saber más respecto de los test.

Bon appétit 🍽!

Ahora tenes listo tu tutorial para alimentar a la comunidad

Podes hacer un pull request a este repositorio que estoy manteniendo y donde estoy listando todos los cursos generados con este framework y otro material util para generar tu propio curso.

Gracias

Me gustaría agradecer a Noam Ross, Julia Silge, Ines Montani y Ted Laderas por dejar el material de sus cursos disponibles de manera gratuita.

HUGOMORE42