diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 408cbc33c..f6e9b3a86 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,23 +1,280 @@ -# Cómo contribuir a este repo +# Contribución -Este repositorio es un recurso abierto, y como tal estamos todos invitados a -participar. +## Índice -## Sugerencias, errores y comentarios generales +* [Cómo contribuir a este repo](#cómo-contribuir-a-este-repo) + * [Sugerencias errores y comentarios generales](#sugerencias-errores-y-comentarios-generales) + * [Para ayudar con review, validación y sugerencias de contenido](#para-ayudar-con-review-validación-y-sugerencias-de-contenido) + * [Para mejorar o crear contenido](#para-mejorar-o-crear-contenido) +* [Guía de Desarrollo](#guía-de-desarrollo) + * [Git workflow](#git-workflow) + * [Viendo cambios](#viendo-cambios) + * [Estilo](#estilo) + * [Estilo Editorial](#estilo-editorial) + * [Configuración de Editor de Texto](#configuración-de-editor-de-texto) + * [Markdown](#markdown) + * [JavaScript](#javascript) +* [Creación de Contenido](#creación-de-contenido) + * [Buenas practicas](#buenas-prácticas) + * [Tópicos](#tópicos) + * [Proyectos](#proyectos) -El lugar donde empezar es nuestro +## Cómo contribuir a este repo + +Este repositorio es un recurso abierto, y como tal estamos toas y todos +invitados a participar. Puedes contribuir con sugerencias, ideas, cambios, +reportes de errores o bugs, comentarios en pull requests o conversaciones de +issues. + +### Sugerencias, errores y comentarios generales + +Si quieres comentar o añadir sugerencias, o reportar un error, +el lugar donde empezar es nuestro [_issue tracker_](https://github.com/Laboratoria/bootcamp/issues). Ahí puedes buscar y ver si tu pregunta o sugerencia ya se ha preguntado antes, participar en discusiones relevantes y añadir nuevos _issues_. -## Ayuda con review, validación y sugerencias de contenido +### Para ayudar con review, validación y sugerencias de contenido + +Busca _issues_ con los tags [`help-wanted`](https://github.com/Laboratoria/bootcamp/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) +o [pull requests abiertos en review](https://github.com/Laboratoria/bootcamp/pulls) y +participar en las conversaciones. + +### Para mejorar o crear contenido + +Si tienes ganas a arreglar un error o un issue existente, lee las secciones de +Guía de Desarrollo para aprender como escribir, probar +y mandar su código. Si no existe un issue pero son cambios menores, +o tienes muy claro qué cambiar y cómo, lo ideal es pull request directamente +y describir el issue/error en la descripción de PR. + +Para crear nuevo contenido, el trabajo necesita tener un issue para describir el +propósito de trabajo y conversar con la comunidad de la idea. +Puede ser [un issue que ya existe](https://github.com/Laboratoria/bootcamp/issues) +o puedes crear un nuevo issue. Si es un nuevo issue, +intenta conversar con el equipo de contenido de curricula, y otras coaches, +si el cambio propuesto es válido y le hace sentido a las demás. + +De igual manera, te invitamos a leer las secciones de Guía de Desarrollo +para aprender como construir nuevo contenido (ya sea de proyectos o tópicos), +testear y enviar tu código como PR. + +--- + +## Guía de Desarrollo + +El planteamiento general del desarrollo de la curricula se basa intencionalmente +en el modelo de desarrollo de software libre y apunta a aprovechar sus bondades. +Si no tienes un perfil técnico y todo esto te suena raro, no te preocupes, +la comunidad está acá para ayudar y guiar. + +### Git workflow + +En el repo seguimos un modelo de colaboración basado en forks. +__Cada una trabaja en su fork.__ Como repo público cualquiera puede +hacer un fork en su cuenta, hacer los cambios que considere y enviar +propuestas de cambios desde su fork en un pull request (PR). + +* Cambios (PRs) normalmente se envían de una rama de su fork a Laboratoria/main. +* Toda propuesta de cambios (PR) tendrá que pasar peer-review y tareas de validación, + linting y pruebas unitarias (npm test). +* Antes de enviar un PR siempre revisa primero el issue tracker para ver si ya existe + una conversación al respecto. + +Si no estás segura de cómo enviar un PR o si deberías hacerlo, lo mejor es comenzar +por un issue. + +### Commits + +TODO: describir estilo https://www.conventionalcommits.org/ + +### Viendo tus cambios + +Cuando estas haciendo cambios a contenido puedes visualizar los cambios corriendo el sitio +de curricula localmente con estos pasos: + +1. Corre `npm test` para ver si los cambios han afectado los tests. +2. Corre `npm run build:content` para crear/actualizar los jsons de tópicos y + proyectos de los cuales la App de React del repo se alimenta. +3. Correr `npm start` para correr el server y navegar al sitio, o + también puedes hacer `npm run watch` para poder visualizar los cambios en + vivo sin tener que estar actualizando el sitio. + +Puedes navegar hacia los proyectos y topicos en el sitio localmente. + +También puedes visualizar los cambios de READMEs de proyecto en otras maneras. + +1. Directamente en VSC con un preview de markdown. +2. Empujando los cambios a tu rama y navegando al README en tu rama en tu fork. +3. Corriendo el script [`create-cohort-project`](./scripts/create-cohort-project.mjs) + para ver el proyecto generado tal cual como las coaches se lo compartirán a + las estudiantes. + +*** + +### Estilo + +El contenido que se vaya creando en este repo debe seguir una serie de +**convenciones** a nivel de **estilo**, **formato** y **estructura** con los +siguientes objetivos: + +* Crear una **experiencia consistente** +* Sacar el máximo provecho al **proceso colaborativo** +* Poder **analizar los cursos de forma programática** para después ofrecer la + experiencia de aprendizaje a nuestras estudiantes + +Estas convenciones se irán documentando acá e irán evolucionando en el tiempo, +así que no dudes en proponer mejoras o cambios. + +Para facilitar el proceso de _code review_ y colaboración en general, creemos +que es esencial seguir una guía de estilos clara, que dé consistencia a la +malla en general. + +Es responsabilidad de lxs mantenedores de este repo asegurar que se cumplen +las convenciones. Hay autorxs que no son necesariamente programadorxs y en este +aspecto la comunidad, y en particular Laboratoria, deben apoyar y guiar en los +temas técnicos. Este proyecto adopta un modelo propio del desarrollo de software +para diseñar contenido, así que nos toca tener flexibilidad para creadorxs a la +vez que aseguramos estándares de estilo, estructura y formato para poder +analizar estos cursos de forma programática. + +[El estilo es importante](https://www.smashingmagazine.com/2012/10/why-coding-style-matters/). + +Las guías de estilo se dividen en: + +* [Estilo editorial](#estilo-editorial) +* [Configuración de editor de texto](#configuración-de-editor-de-texto) +* [Markdown](#markdown) +* [Javascript](#javascript) -Busca _issues_ con los tags [`help-wanted`](https://github.com/Laboratoria/bootcamp/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22). +#### Estilo editorial + +A tener en cuenta a la hora de escribir... + +* Tono coloquial (tú en vez de usted) +* Narración dirigida a la estudiante como lectora, 2da persona, singular (ie: en esta + lección aprenderás a ...) +* **Femenino genérico o `x` para neutro (ie: `Todxs lxs programadorxs`)** TODO: resalta eso o cambiar/omitirlo - el x se dificulta lecturas de pantalla +* [El adverbio solo y los pronombres demostrativos, sin tilde](http://www.rae.es/consultas/el-adverbio-solo-y-los-pronombres-demostrativos-sin-tilde) +* Marcado semántico (ie: usar `blockquotes` para _citas_ y solo citas) +* Frases cortas + +#### Configuración de editor de texto + +La mayoría del contenido (pero no todo) se desarrolla en archivos de texto +plano. Para manejar archivos de texto (`.md`, `.js`, `.html`, ...) vas a +necesitar un editor de texto. Puedes usar tu editor favorito, y si todavía no +tienes uno te recomendamos [VS Code](https://code.visualstudio.com/). + +Para definir y mantener convenciones de uso de espacios y otras características +configurable en un editor de texto el repo incluye un archivo +[`.editorconfig`](https://github.com/Laboratoria/bootcamp/blob/main/.editorconfig), +que es un estándar para manejar este tipo de convenciones. Más info en +[editorconfig.org](http://editorconfig.org/). + +Esta configuración funciona con la mayoría de editores populares. + +#### Markdown + +[Markdown](https://daringfireball.net/projects/markdown/syntax), en particular +[GitHub Flavored Markdown](https://guides.github.com/features/mastering-markdown/), +es el formato más común en la currícula. Si no estás familiarizada con Markdown, +acá tienes un +[Cheat Sheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) +muy útil. + +Para facilitar la tarea de validar las convenciones a nivel de Markdown, el +repo incluye una _tarea_ que verifica el _estilo_ del Markdown usando un linter. +Esta tarea se ejecuta automáticamente al enviar un pull request. +Alternativamente, también la puedes ejecutar directamente en tu copia local con +el comando `npm run mdlint` (esta tarea también se ejecuta cuando hacemos +`npm test`). + +#### JavaScript + +Por ahora hemos [acordado](https://github.com/Laboratoria/bootcamp/issues/11) +usar la guías de estilo de [AirBnB](https://github.com/airbnb/javascript), en +particular usando: + +* [`eslint-config-airbnb-base`](https://www.npmjs.com/package/eslint-config-airbnb-base) +* [`eslint-config-airbnb`](https://www.npmjs.com/package/eslint-config-airbnb) + +Los ejemplos, snippets, y proyectos de ejemplo de Laboratoria deberían usar +el mismo estilo. ## Creación de contenido -Si tienes una idea para un curso, chequea el +La malla curricular está compuesta de _proyectos_ y _tópicos_. + +Los contenidos desarrollados en este repo deben seguir una estructura y una +serie de convenciones para después poder ser analizado y convertido de forma +automatizada a una estructura de datos que pueda ser usada por nuestro _LMS_ +(Ver [`curriculum-parser`](https://github.com/Laboratoria/curriculum-parser)). + +Si tienes una idea para un curso o proyecto, chequea el [issue tracker](https://github.com/Laboratoria/bootcamp/issues) y el [`README.md`](README.md) para ver si ya se ha propuesto algo parecido. Si tu -propuesta es algo nuevo, abre un issue con tu idea y veamos que opina la +propuesta es nueva, abre un issue con tu idea y veamos que opina la comunidad. + +TODO: donde mencionamos el siguiente: + +Dependiendo de la naturaleza del contenido, se decidirán los detalles +exactos ya que no todos los proyectos o tópicos tienen la misma naturaleza._ + +### Buenas prácticas + +- **Mantener tus contenidos DRY** Al momento de planear un contenido, tener en + consideración que ya existe material (videos, entradas de blog, etc) muy + bueno en internet que únicamente necesita traducirse. Generar contenido + desde 0 es difícil. Traducir y dar crédito, no tanto. +- **Manejo de archivos binarios** +Ver [#114](https://github.com/Laboratoria/bootcamp/issues/114#issuecomment-321457379). + +### Tópicos + +Un tópico siguen un formato en particular. Nuevos tópicos necesitan nuevo +directorio dentro de carpeta [`/topics`](./topics/) con el nombre del tópico, +y dentro eso creas directorios por cada _unidad_. + +Para aprender como estructurar un tópico, lee [la guía de tópicos](./contributing/TOPICS.md) + +Cuando estés creando contenido o haciendo cambios puedes visualizarlos +corriendo el sitio de curricula localmente como +[se explica anteriormente](#viendo-cambios). + +### Proyectos + +Puedes encontrar los proyectos de la curricula en el directorio +[`projects`](./projects/). + +Cada proyecto tiene su propio directorio con el boilerplate necesario y +su enunciado en el archivo README. + +Para aprender como estructurar un proyecto, revisa [la guía de Proyectos](./contributing/PROJECTS.md) + +Si haces cambios a un README y o agregas objetivos de aprendizaje al proyecto +y quieres ver como parece el proyecto en su totalidad, + +usa el script [`create-cohort-project`](./scripts/README.md#create-cohort-project) +para generar el proyecto localmente (no es necesario empujarlo a Github). + +Este script crea la sección de Objetivos de Aprendizaje del proyecto a partir +del archivo `project-yml` que lo acompaña y que enlista los OAs asociados a él. + +También puedes ir viendo el resultado corriendo el sitio de curricula +localmente como [se explica anteriormente](#viendo-cambios). + +Otro script que debes ejecutar mientras realizas cambios a un README de un +proyecto es `npm run mdlint` que va a ejecutar el linter que va a analizar los +archivos Markdown y resaltar errores. Si no se ejecuta de manera local, de +igual forma será ejecutado en una Github Action cuando abras tu PR, +recomendamos ejecutarlo de manera local de manera de arreglar errores de estilo +que puedan haber de manera que luego la Github Action asociada pase +satisfactoriamente sin errores. + +Si haces cambios con que impacten directamente el _boilerplate_ de un proyecto, +o derechamente si quieres proponer un nuevo proyecto, es necesario contar con +una implementación modelo del proyecto de manera de entender cualquier caso +borde o _caveat_ que pueda haber con respecto al enunciado, OAs, o tecnología +asociada a la solución propuesta para ese proyecto. diff --git a/contributing/PROJECTS.md b/contributing/PROJECTS.md new file mode 100644 index 000000000..1a7d8cac4 --- /dev/null +++ b/contributing/PROJECTS.md @@ -0,0 +1,145 @@ +# Guía de Proyectos + +## Anatomía de un proyecto + +* Las carpetas de _proyectos_ siguen la nomenclarura `00-slug`, donde `00` son + dos dígitos que expresan una intención de ordenado, y el `slug` es un string + único para cada _proyecto_, en minúsculas y de entre `1` y `97` caracteres. + Expresado como `RegExp` sería algo como `^\d{2}-[a-z\-]{1,97}$`. Longitud + máxima del nombre de carpeta son `100` caracteres. +* El único archivo obligatorio es el `README.md`. +* Todo lo demás se considera _boilerplate_. + +## project.yml + +## `README.md` + +Lo mejor es ver un par de ejemplos como +[`cipher`](../tree/master/projects/01-cipher) o +[`burger-queen`](../tree/master/projects/04-burger-queen). + +* Debe comenzar con un `

` con el _título_ del proyecto. +* Justo después del título debe incluir un _índice_ (TOC). +* El índice debería incluir solo un nivel del árbol, a menos de que haya un + motivo especial que lo justifique. +* Inmediatamente después cerramos el índice con un `
`. +* El índice no debe listarse a sí mismo. No hay necesidad de incluir el índice como primer elemento del índice. +* Los elementos del indice estarán numerados. Esto hace más fácil digerir y manejar la información del proyecto. + +Ejemplo de título y TOC: + +```md +# Título + +## Índice + +* [1. Preámbulo](#1-preámbulo) +* [2. Resumen del proyecto](#2-resumen-del-proyecto) +* [3. Objetivos de aprendizaje](#3-objetivos-de-aprendizaje) +* [4. Consideraciones generales](#4-consideraciones-generales) +* [5. Criterios de aceptación mínimos del proyecto](#5-criterios-de-aceptación-mínimos-del-proyecto) +* [6. Pistas, tips y lecturas complementarias](#6-pistas-tips-y-lecturas-complementarias) + +*** +``` + +https://github.com/Laboratoria/bootcamp/blob/1b99054d798e945dcb863b4d14f7ea91dd53d726/projects/01-cipher/README.md?plain=1#L1-L16 + +### Secciones + +Cada sección (obligatoria o no) comienza con un `

` con el título de la +sección. Para facilitar la navegación y conversación sobre los proyectos usamos +un prefijo numérico (como lista numerada). + +#### Secciones obligatorias + +* 1. Preámbulo +* 2. Resumen del proyecto +* 3. Objetivos de aprendizaje +* 4. Consideraciones generales +* 5. Criterios de aceptación mínimos del proyecto +* 6. Pistas, tips y lecturas complementarias + +Ejemplo de secciones: + +```md +## 1. Preámbulo + +Entre 1 y 3 párrafos dándo contexto al proyecto, las tecnologías y herramientas +involucradas, por qué es importante/útil aprender esto. Qué esperar del proyecto +(desde el punto de vista de la estudiante). + +## 2. Resumen del proyecto + +Un explanación de concepto de proyecto, mejor con un ejemplo y contexto. + +## 3. Objetivos de aprendizaje + +Este sección debe que estar en algun parte de proyecto (no importa el orden) +pero con el titulo `Objetivos de aprendizaje`. El script de curriculum parser +inserta los objetivos en este seccion, usando los que estan listado en el `project.yml`. + +## 4. Consideraciones generales + +Este proyecto se debe "resolver" de forma [individual/duplas/tríos/...]. + +Blah blah blah... + +## 5. Criterios de aceptación mínimos del proyecto + +### Definición del producto + +Blah blah blah... + +*** + +#### [Historia de usuario 1] Blah blah blah... + +Blah blah blah... + +##### Criterios de aceptación + +Lo que debe ocurrir para que se satisfagan las necesidades del usuario) + +* ... + +##### Definición de terminado + +Lo acordado que debe ocurrir para decir que la historia está terminada. + +* ... + +*** + +## 6. Pistas, tips y lecturas complementarias + +### Primeros pasos + +Blah blah blah... + +### Otros recursos + +Blah blah blah... +``` + +#### Secciones opcionales + +* Hacker edition +* Consideraciones técnicas (más detalles técnicos :see_no_evil:) +* Checklist + +### Learning Objectives + +Los Objetivos de Aprendizaje (Learning Objectives) tambien son abiertos a evolucionar. +Cada proyecto viene con objetivos que definimos en su `project.yml`. + +Los objetivos que encuentran en el `proyect.yml` de un proyecto son solo algunos, +la lista completo esta en [`learning-objectives/data.yml`](./src/learning-objectives.data.yml){:target="_blank"}. + + Con esta lista definimos los objetivos completos, traducidos, en formato yaml + que se encuentra en [`learning-objectives/intl`](./src/learning-objectives.data.yml){:target="_blank"}. + + Para proponer cambios... + + Para proponer nuevos... + diff --git a/contributing/TOPICS.md b/contributing/TOPICS.md new file mode 100644 index 000000000..a1215b5d1 --- /dev/null +++ b/contributing/TOPICS.md @@ -0,0 +1,302 @@ +# Guía de topics + +## Anatomía de un tópico + +Dentro de cada carpeta de _tópico_ debe haber un archivo `README.md` +con la información general del tópico. + +Estructura de archivos de un tópico: + + + +```text +topic-slug # tópico +├── 01-unit-slug # unidad +│   ├── 00-opening # parte +│   │   └── README.md +│   ├── 01-part-title-1 +│   │   └── README.md +│   ├── 02-part-title-2 +│   │   └── README.md +│   ├── 03-example-exercise +│   │   ├── 01-print-primes #challenge +│   │   │   ├── README.md +│   │   │   ├── boilerplate +│   │   │   │   └── printPrimes.js +│   │   │   ├── solution +│   │   │   │   └── printPrimes.js +│   │   │   └── test +│   │   │   └── printPrimes.spec.js +│   │   └── README.md +│   └── 04-closing +│   └── README.md +├── 02-unit-slug/ +│ └── ... +├── 03-unit-slug/ +│ └── ... +└── README.md +``` + +_slug_ significa title o identificador de tópico. + +Nombres de archivos y carpetas en minúsculas, usando `-` en vez de espacios y +evitando caracteres especiales. + +## `README.md` principal del _tópico_ + +Cada tópico empieza por un archivo `README.md`. +Una manera de familiarizarse con la estructura de este archivo es ver +[este ejemplo de template](https://github.com/Laboratoria/bootcamp/blob/main/topics/_template/README.md). + +El `README` debe tener: + +1. Track de tópico `track` (`web-dev`, `ux`, etc) +2. Título(`title`) _required_ + +~* Descripción (`description`)~ _required_ +~* Tags: (`tags`)~ _required_ +3. Syllabus (`syllabus`) _required_ +4. Requerimientos previos, si hay (`dependencies`) _required_ +~* Público objetivo (`targetAudience`)~ _required_ + + +~* Evaluación (`grading`)~ _required_ +~* Contribuidores (`contributors`)~ _required_ + +Partes adicionales: + +* Producto(s) a desarrollar (`product`) por unidades de track `ux` +* Libros (`books`) +* Benchmarks (`benchmarks`) +* Referencias (`references`) + +### Track (requerido) + +El track parece en el front-matter de Markdown. + +``` md +--- +track: ux +--- +``` + +### Título (requerido) + +La primera línea del `README.md` de un tópico debe contener un `h1` con el título +completo. + +```md +# Título del tópico +``` + +### Syllabus (requerido) + +El syllabus esta marcado en `h2` (`##` en Markdown) y contiene +los títulos de los unidades marcado como `h3` y con links +al directorio del unidad. + +Opcionalmente cada titulo de unidad tiene una descripción de unidad. + +``` md +### Unidad 01: [Tu primera página web](01-intro) + +En esta unidad crearás tu primera página web. +``` + +... + +## Anatomía de Unidades + +Los unidades son los directorios que encuentras dentro un +tópico y que contiene el contenido de partes. + + + + +Estructura de archivos: + +```text +0X-topic-slug +├── 01-titulo-corto-unidad/ # unidad +│   ├── 00-apertura # parte +│ │  └── README.md +│   ├── 01-titulo-corto +│ │  └── README.md +│   ├── 02-practice +│ │  ├── 01-un-ejercicio +│ │  ├── 02-otro-ejercicio +│ │  └── README.md +│   ├── 03-some-quiz +│   ├── 04-ejercicios-guiados +│   ├── 05-solucionario +│   └── 06-cierre +├── 02-titulo-corto-unidad/ +└── README.md +``` + + +Recomendamos que cada unidad empiece con una parte _lectura_ de **apertura** o +**opening** y termine con una de **cierre** o **closing**. +Por ejemplo, la unidad 01 arriba tiene `00-apertura`, `06-cierre`. + +## Anatomía de una _parte_ (actividad) de una _unidad_ + +Cada parte es un directorio dentro un unidad, y debe tener +su propio `README.md`. + +El `README.md` debe tener: + +1. Tipo de parte (`type`) _required_ +2. Duración (`duration`) _required_ +3. Titulo de unidad (`title`) _required_ +4. Objetivos de aprendizaje (`learningObjectives`) _required_ +5. Contenido/cuerpo _required_ + +```text + +front-matter +--- + type * + format * + duration * +--- + +h1 (título) * +h2 (objetivos de aprendizaje) +ul + li (objetivo de aprendizaje 1) + li (objetivo de aprendizaje 2) + li (objetivo de aprendizaje n) +hr * +body (el cuerpo/contenido) + +* obligatorio +``` + +### Tipo, Format y Duración + +Esta información o metadata parece en el front-matter de un parte. + +``` md +--- +type: read +format: self-paced +duration: 30min +--- +``` +Los tipos son `lectura/read`, `práctica/practice`, `cuestionario/quiz`, +`self-paced` (Leer mas de tipos y formatos.)[] + +Los formatos son self-paced y guiado (deprecated). + +Duración puede calcular como ... + +### Título (requerido) + +La primera línea del `README.md` de un parte debe contener +un `h1` con el título completo. + +### Objetivos de Aprendizaje + +Una lista de puntos o breve descripción de que va a aprender en este parte. + +### Contenido de parte + +Puede tener las secciones necesarias con sus propios títulos. +Por favor usa markup semantica como encabezados, listas, y links +donde correcto. + +Algunas secciones que otras partes tienen - +* Guía de preguntas y conceptos clave (`keyConcepts`) +* No se si hay otros ejemplos + +#### Sobre Tipos y Formatos + +* `seminario/seminar` (deprecated/legacy) + Un seminario es lo más parecido a una clase presencial tradicional. Los + seminarios son _guiados_ por unx o más instructoras. +* `lectura/read` + Las lecturas son artículos de contenido que pueden incluir videos, imágenes y + otros soportes, embebidos o como vínculos externos. +* `práctica/practice` + Las prácticas principalmente ejercicios y pueden tener diferentes entornos: +`js`, `web`, `node`, ... +* `cuestionario/quiz` + Los cuestionarios a corto plazo se manejarán como links a Google Forms. Más + adelante se implementará una manera más apropiada para poder incluir en nuestro + LMS. +* `taller/workshop` (deprecated/legacy) + Los talleres (o workshops) son sesiones guiadas o no guiadas (self-paced) + durante las cuales las alumnas realizan una actividad prolongada, como + implementación, diseño o investigación. Al final de un taller o grupo de + talleres normalmente se cierra con una demo o presentación. + +#### Formato + +Cualquiera de los _tipos_ de contenido anteriores pueden darse (o proponerse) en +dos formatos: + +* `guiado/guided` (deprecated/legacy) +Los contenidos guiados son aquellos donde la _clase_ es dirigida por unx o más +instructorxs. Los seminarios son siempre guiados, mientras que los talleres, +lecturas o ejercicios pueden ser guiados o no. +* `self-paced` +Los contenidos _self paced_ (a tu propio ritmo) son aquellos que están dirigidos +por las alumnas y por lo general podrían ver estas partes en su propio tiempo. +En este formato, lxs instructorxs tienen el rol de acompañar, guíar y apoyar, +pero son ellxs quienes dirigen la actividad. + + +### Challenges + +Challenges composeen los partes de normalmente llaman +`practice`, `code-challenges` o `exercises`. + +```text +0X-topic-slug +├── 01-titulo-corto-unidad/ # unidad +│   ├── 00-apertura # parte +│   ├── 01-titulo-corto +│   ├── 02-practice +│ │  ├── 01-un-ejercicio # challenge +│ │ │ ├── boilerplate +│ │ │ │ └── un-ejercicio.js +│ │ │ ├── solution +│ │ │ │ └── un-ejercicio.js +│ │ │ ├── test +│ │ │ │ └── un-ejercicio.spec.js +│ │ │ └──README.md +│ │  ├── 02-otro-ejercicio +│ │  └── README.md************* // TODO describe que hace aqui? +├── 02-titulo-corto-unidad/ +└── README.md +``` + +Cada challenge es un directorio que contiene: + +1. README.md +2. directorio `boilerplate` con un archivo js que sirve + como plantilla del ejercicio +3. directorio `solution` con un archivo js que tiene el reto + resuelto +4. directorios `test` con un spec.js con pruebas para + verificar la solución + +El `README.md` explica el reto / problema con links a conceptos +para revisar. Necesitan este front matter para designarlo como +`CommonJS`. + +``` +--- +env: cjs +--- +``` + +El boilerplate contiene un archivo js que es un template de +la función o markup para resolver. La función es exportado con +un `module.exports` si es necesario. + +El spec contiene un grupo de tests que van a correr para chequear la +solución del reto. + diff --git a/topics/_template/README.md b/topics/_template/README.md index f5d1c6090..0d905bf2e 100644 --- a/topics/_template/README.md +++ b/topics/_template/README.md @@ -1,3 +1,7 @@ +--- +track: ... +--- + # Título del tópico Dos o tres párrafos explicando el tópico en líneas generales. Introducción al