Apéndice I — Darlo como taller

Palabras clave

Quarto, publicación reproducible, agentes de programación, Markdown, Python, EPUB, análisis de datos, k-means

El libro sigue un taller práctico de seis horas, y se puede enseñar de esa manera: 300 minutos de enseñanza en cuatro sesiones, de 65, 65, 85 y 85 minutos, con dos descansos de 15 minutos y una comida de 30 minutos. Las diapositivas del taller, en inglés, son el material del curso el día del taller; este libro es la lectura detrás de ellas. Los participantes hacen en casa, antes del día, la preparación del Capítulo 4 y la lectura sobre los agentes, los costos, las políticas de IA y Markdown.

El Capítulo 5, el primer informe a mano, es solo del libro: las diapositivas no lo incluyen, y nada del día depende de él. Encaja en el trabajo previo, después de la prueba, porque solo necesita las herramientas y los archivos del taller que instala la preparación, y su punto de partida (starters/first-report/) viene con esos archivos. Ofrécelo como trabajo previo opcional, de unos 45 minutos: quienes lo hacen llegan habiendo renderizado un informe, comparado con sus datos y deshecho un cambio con Git por su cuenta.

El día

La Tabla I.1 y la Tabla I.2 relacionan el día con el libro: el comienzo y la duración en minutos de cada bloque, el punto de control con el que termina, cuando lo hay, y los capítulos que cubre.

Tabla I.1: La mañana del taller: la Parte I y la guía de Londres.
Hora Bloque (su punto de control) Libro
antes Preparación; lectura sobre agentes, costos, políticas de IA y Markdown; opcionalmente, un primer informe a mano 2, 4, 6; 5 (opcional)
0:00 (10) Bienvenida, objetivo, resultado Prefacio
0:10 (5) Qué es Quarto 1
0:15 (15) Antes de pedir: comprobaciones fallidas, los recuadros, los prompts 2
0:30 (35) Londres: de Markdown a HTML, reglas, entorno (01) 6
1:05 (15) Descanso y puesta al día
1:20 (20) Londres: de .md a .qmd, formatos (02) 7
1:40 (15) Londres: tres públicos con subagentes (04) 8
1:55 (20) Londres: publicar en GitHub Pages (examples/london) 9
2:15 (10) Londres: cambiar un dato de entrada 9
2:25 (30) Comida y puesta al día
Tabla I.2: La tarde del taller: el análisis del agua. Si se empieza a las 9:30, la comida es a las 11:55 y el día termina a las 15:30.
Hora Bloque (su punto de control) Libro
2:55 (20) Agua: por qué, reglas, datos (05) 17
3:15 (20) Agua: explorar (05) 18
3:35 (20) Agua: preparar (06) 19
3:55 (25) Agua: agrupar (07) 20
4:20 (15) Descanso y puesta al día
4:35 (20) Agua: interpretar (08) 21
4:55 (15) Agua: correlación y causalidad (09) 22
5:10 (40) Agua: publicar en muchos formatos, cambiar un dato de entrada (10–13, examples/water) 23
5:50 (10) Mostrar los sitios, próximos pasos Epílogo

Los tiempos de los ejercicios son estimaciones de planificación que nunca llenan un bloque: el resto es para las diapositivas de conceptos, mostrar resultados y recuperarse de un comando fallido. Si el lugar fija la hora de la comida, mueve el comienzo, no la comida: la comida va entre las dos partes, para que todo el mundo empiece junto el análisis del agua.

La última diapositiva de la presentación, After Today: Your Own Work, es para avanzar a tu ritmo y no le quita tiempo al día. Les indica a quienes van a usar el método en su trabajo las partes III y IV (capítulos 10 a 16), que parten de la vía rápida, el Capítulo 3, y de sus puntos de control en el repositorio del taller, así que no hace falta terminar antes los proyectos del día. El material profesional del libro es solo del libro: el día de seis horas conserva sus dos proyectos.

Antes del día

  • Reúne las confirmaciones de la prueba. Pídele a cada participante que confirme la comprobación de la preparación y la prueba (Sección 4.7), y contacta a quien no lo haya hecho.
  • Windows. Pide antes del día la salida de wsl -l -v que muestre VERSION 2. Quienes no tengan una cuenta de administrador, o tengan la virtualización desactivada en la BIOS, no pueden instalar WSL: ponlos a trabajar con alguien al lado. El procedimiento para Windows se revisó contra la documentación de Microsoft y en una Mac; ejecútalo una vez en una máquina Windows limpia antes de enseñar.
  • La red. Comprueba que el Wi-Fi del lugar permita GitHub, las descargas de paquetes de uv y GitHub Pages, y que aguante que todo el mundo descargue a la vez.

La regla de los dos minutos

La regla que mantiene unido al grupo: quien lleve dos minutos sin avanzar por un comando, un error del agente o una errata no depura delante de todo el grupo. Pega la línea del ejercicio para ponerse al día (Figura 2), y todo el mundo vuelve a trabajar junto en el bloque siguiente. Muestra una vez cómo ponerse al día, en vivo, al comienzo del primer bloque, para que nadie lo vea como un fracaso. En el bloque de las 0:15, alguien de apoyo se sienta con quien haya fallado en la comprobación de la preparación o en la prueba mientras la persona que presenta sigue adelante.

Desde el bloque de agrupamiento en adelante, mantén al grupo en la ruta normal, que copia el analysis.py terminado de cada bloque. La ruta de desafío, escribir el análisis, es para quienes vayan muy por delante del grupo; los tiempos de la agenda suponen la ruta normal.

Publicar

La primera publicación de cada sitio tarda unos dos minutos desde que se crea la rama gh-pages hasta que se sube el sitio, y luego GitHub Pages lo construye en 20 a 35 segundos (prueba del 2026-11-01). Aprovecha la espera: muestra uno de los sitios de ejemplo terminados, o explica cómo funciona la rama gh-pages. Los tres problemas más comunes son la primera publicación (tiene que ser interactiva), un push que falla con HTTP 400 (sube http.postBuffer) y un renderizado que choca con una vista previa en curso (detén antes la vista previa); el Apéndice D tiene las soluciones.

Revisar los ejemplos antes de enseñar

Después de cualquier cambio en las dependencias, comprueba que los dos proyectos terminados se sigan renderizando:

cd examples/london
uv run quarto render
test -f _site/index.html && test -f _site/london-whitepaper.pdf && echo "Part II OK"

cd ../water
uv run python scripts/analysis.py
uv run quarto render
test -f _site/index.html && test -f _site/dashboard.html && test -f _site/whitepaper.pdf && echo "water OK"