11  Diapositivas que sostienen una decisión

Palabras clave

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

El informe y la ficha del modelo son para personas que leen. La decisión sobre qué versión lanzar se va a tomar en una reunión, frente a una pantalla, entre personas que van a mirar cada diapositiva unos segundos y van a recordar quizá tres. Una presentación para esa sala es otro documento: no un informe cortado en pedazos, sino un argumento breve, una afirmación a la vez, que termina en lo que hay que decidir.

Pocas veces vas a escribir a mano una opción de Reveal.js o una línea de la hoja de estilos de un tema. Lo que necesitas es saber qué puede hacer una presentación, y cómo se llama cada cosa, para poder pedirla; cómo pedirla de modo que el resultado se pueda revisar; y cómo se ve una buena presentación cuando vuelve. Este capítulo construye la presentación de la evaluación para el equipo de producto y sus inversionistas, como una página web que se presenta sola, un PDF para enviar después y un archivo de PowerPoint con la plantilla de la empresa, todo desde una sola fuente que lee los mismos resultados que el informe.

En este capítulo
  • Nombrar lo que hace funcionar una presentación técnica, y las funciones de Reveal.js que la sirven: notas de presentación, fragmentos, columnas, temas y vista de impresión.
  • Pedir una presentación cuyos títulos enuncien afirmaciones calculadas a partir de los resultados, protegidas por guardas, con el detalle en las notas.
  • Comprobar con una prueba los colores de un tema contra el mínimo de contraste de WCAG.
  • Exportar la presentación a PDF y a PowerPoint con una plantilla de la casa, y saber qué pierde cada formato.

Partes detu repositorio acme-eval al final del Capítulo 10, o checkpoints/15-eval-results/.

Construyesslides.qmd como presentación de Reveal.js, un PDF y un archivo de PowerPoint, con un tema, una prueba de contraste y una plantilla de referencia.

Punto de controlcheckpoints/16-eval-slides/

11.1 Qué hace que una presentación técnica funcione

Una presentación tiene éxito cuando la sala sale sabiendo la afirmación, la evidencia que la respalda y lo que se decidió. Cinco hábitos llevan hasta ahí, y cada uno es algo que puedes pedirle a un agente y revisar:

Tabla 11.1: Cinco hábitos de una presentación técnica, y cómo revisar cada uno.
Hábito Qué significa Revisas
Una afirmación por diapositiva cada diapositiva plantea una idea, con una sola evidencia ninguna diapositiva necesita dos oraciones para decir lo que muestra
El título enuncia la afirmación “v3 reaches 43.6% of subscribers…”, no “Results” lee solo los títulos, en orden: son el argumento
Números calculados, palabras protegidas los números de un título son código en línea; su redacción tiene una guarda los títulos coinciden con outputs/, y una guarda detiene uno falso
El detalle en las notas las notas de presentación tienen lo que vas a decir; la diapositiva tiene la afirmación y su evidencia cada diapositiva tiene notas; ninguna diapositiva es un párrafo
Terminar en la decisión la última diapositiva dice qué se está decidiendo la sala sabe qué estás pidiendo

El segundo hábito es el que más trabajo hace. Lee solo los títulos de la presentación terminada y tienes su argumento: el titular, la comparación, el ordenamiento, a quién se llama, cuánto se puede confiar en las probabilidades, lo que los resultados no muestran, y la decisión. Su título principal, en la ejecución de este libro, es “v3 reaches 43.6% of subscribers by calling a tenth of the list” (llega a esa proporción de quienes se suscriben llamando a una décima parte de la lista), con cada número y la fracción calculados a partir de outputs/.

11.2 Qué puede hacer una presentación, y cómo se llama

Quarto hace presentaciones en dos formatos desde una sola fuente: Reveal.js, una página web que se presenta sola en cualquier navegador, y PowerPoint. Cada título ## empieza una diapositiva en los dos. El resto es vocabulario: funciones que pides por su nombre.

Tabla 11.2: Lo que puede hacer una presentación, cómo se llama y en qué se diferencia entre formatos (Quarto 1.10.20).
Pide Quarto lo llama Notas
notas de presentación un bloque ::: {.notes} en la diapositiva se ven en la vista del presentador, no en la pantalla; en PowerPoint van al panel de notas
puntos que aparecen de a uno fragmentos: . . . entre párrafos, o ::: {.fragment} listas estáticas en PowerPoint
dos columnas :::: {.columns} con bloques ::: {.column width="50%"} adentro el diseño Two Content de PowerPoint
una diapositiva con más texto, más pequeño la clase {.smaller} en el título; {.scrollable} permite desplazarla úsalo poco: mejor divide la diapositiva
un enlace estable a una diapositiva un ID en el título, ## … {#decision} la dirección termina en #/decision
un tema theme: [default, acme.scss]: un tema incluido más tu propio archivo Sass colores y fuentes en un solo lugar
un pie de página y números de diapositiva footer: y slide-number: true solo Reveal.js
un PDF la vista de impresión de Reveal.js: presiona E y luego imprime desde el navegador no hay --to pdf para presentaciones
la vista del presentador presiona S mientras presentas una segunda ventana con las notas
una plantilla de PowerPoint de la casa reference-doc: con un .pptx hecho a partir del predeterminado de Quarto colores, fuentes y diseños

11.3 La presentación

El prompt reúne los cinco hábitos y el vocabulario, más dos frases que esquivan trampas encontradas al probarlo, que se explican más abajo. Pide una sola presentación, como una sola tarea, porque sus comprobaciones se ejecutan sin ti: las guardas, el renderizado y los títulos que enumera.

Pídele a tu agente
Crea slides.qmd, una presentación de Reveal.js a 1280×720 para el equipo de producto y los inversionistas, escrita en inglés, solo a partir de outputs/: un título y un subtítulo YAML simples (sin código en línea), y luego siete diapositivas, una afirmación por diapositiva, con el título de cada diapositiva enunciando su afirmación y cualquier número como código en línea, notas de presentación en cada una de las siete, las curvas ROC y a quién se llama por franja de edad como figuras de matplotlib con texto alternativo y sin etiquetas `fig-`, una diapositiva de dos columnas que compare v2 y v3, y las advertencias reveladas de a una. Pon una guarda en cada título cuya redacción dependa de los resultados. Renderízala y enumera los títulos de las diapositivas.
Probablemente ejecute

escribe slides.qmd · uv run quarto render slides.qmd → slides.html

Tú haces

abre slides.html · presiona S para la vista del presentador, y E para la vista de impresión

Lee primero los títulos, en el orden en que los enumera el agente: deberían ser el argumento. Luego la fuente: los números de cada título son código en línea, cada afirmación de un título tiene una guarda en la celda anterior, y cada diapositiva tiene un bloque de notas. Preséntala: presiona S, y la vista del presentador se abre en una segunda ventana con las notas, que es lo que vas a ver mientras la sala ve la diapositiva.

AdvertenciaError frecuente

Trampas encontradas al construir y probar la presentación, y las razones de dos frases del prompt. El código en línea en el title del YAML se ejecuta antes que cualquier celda y falla con un NameError, y sin título en el YAML, Quarto convierte el primer título de diapositiva en el título de la presentación, sin calcular; de ahí “un título y un subtítulo YAML simples”. Las notas escritas antes del primer título ## se convirtieron en una diapositiva extra, en blanco, así que el prompt pide notas en las siete diapositivas que siguen al título; la presentación terminada le agrega las notas a la diapositiva de título con un filtro corto, filters/title-notes.lua. Una celda de figura con la etiqueta fig-… agrega “Figure 1:” a su pie, algo que las diapositivas pocas veces quieren; de ahí “sin etiquetas fig-”. Más allá del prompt: un ajuste fig-dpi les dio a las figuras un tamaño fijo que se salía de la diapositiva; en otra ejecución, sin ese ajuste, las figuras ocupaban menos de la mitad. El tema de la presentación terminada les da a las figuras una altura fija, así que mira cada diapositiva al tamaño de la presentación. Y un conteo impreso directamente desde pandas decía np.int64(6) hasta que se convirtió en un int simple: lee cada título renderizado, no solo la fuente.

11.4 Un tema que se puede leer

Un tema es donde viven los colores y las fuentes de una presentación, y es donde la mayoría de las presentaciones le fallan a su público: un texto gris pálido sobre blanco es ilegible en un proyector. Las Pautas de Accesibilidad para el Contenido Web (WCAG) fijan el mínimo: una relación de contraste de 4.5 a 1 entre el texto y su fondo (WCAG 2.2, criterio de conformidad 1.4.3). Una prueba puede comprobarlo, así que pide la prueba junto con el tema:

Pídele a tu agente
Agrega acme.scss, un tema de Reveal.js sobre `default`: tinta oscura sobre un fondo blanco hueso cálido, un azul marino para los títulos y los enlaces, fuentes del sistema. Agrega tests/test_deck_contrast.py, que compruebe que el texto del cuerpo y los enlaces tengan una relación de contraste de al menos 4.5:1 sobre el fondo (WCAG 2.2), ejecuta la prueba y renderiza la presentación.
Probablemente ejecute

escribe acme.scss y la prueba · uv run pytest · renderiza la presentación

Los colores del tema terminado, medidos con la fórmula de las pautas:

Tabla 11.3: Los colores de texto del tema terminado sobre su fondo, #fbfaf7, calculados con la fórmula de WCAG 2.2, a partir de las variables que comprueba su prueba.
Texto Color Contraste sobre el fondo
cuerpo #1b2733 14.5:1
títulos #0b3d63 10.8:1
enlaces #0b5cad 6.4:1
pies de figura, pie de página #4a5663 7.2:1

La prueba vuelve permanente la regla: un cambio de color posterior que no la cumpla hace fallar el conjunto de pruebas, antes de que alguien tenga que forzar la vista frente a un proyector. Hay algo a lo que un tema no llega: matplotlib dibuja sus figuras sobre blanco, que se ve como un recuadro blanco sobre una diapositiva blanco hueso. La presentación terminada las dibuja sobre un fondo transparente. El color no es lo único que hace legible una presentación, así que mantén también los otros hábitos: etiquetas de figura legibles desde el fondo de la sala, colores que se diferencien en luminosidad además de en tono, y texto alternativo en cada figura.

11.5 Un PDF para enviar después

Después de la reunión, alguien va a pedir las diapositivas. Quarto 1.10.20 no tiene un formato PDF para presentaciones de Reveal.js; el camino es la vista de impresión de Reveal.js, impresa por un navegador. A mano: abre la presentación, presiona E e imprime a PDF. Para que sea parte del build, un script puede hacer lo mismo con Chrome sin interfaz (headless) y revisar su propio resultado:

Pídele a tu agente
Escribe scripts/deck_pdf.py: que imprima slides.html a slides.pdf con Chrome headless en `?print-pdf`, pasando `--run-all-compositor-stages-before-draw`, que compruebe que el PDF tenga una página por diapositiva y que lo reintente hasta tres veces si no es así. Ejecútalo y dime la cantidad de páginas.

La opción y la comprobación son, las dos, lo importante. Impreso desde la línea de comandos, Chrome a veces imprimía antes de que la presentación terminara de acomodarse y escribía una sola página en blanco; en las pruebas para este libro eso pasó en la mayoría de las ejecuciones sin la opción, que hace que Chrome termine de dibujar la página antes de imprimir, y en ninguna con ella. La comprobación, una cantidad de páginas que debe ser igual a la cantidad de diapositivas, atrapó cada impresión en blanco, y también atrapa una diapositiva demasiado alta para su página, que Reveal.js imprime en dos. Convierte una falla en un reintento en lugar de un PDF en blanco en la bandeja de entrada de un cliente.

11.6 PowerPoint, con la plantilla de la casa

Muchas organizaciones hacen circular sus presentaciones como PowerPoint, en una plantilla con sus colores, sus fuentes y su logo. Quarto renderiza PowerPoint desde la misma fuente, y un documento de referencia lleva la plantilla: un archivo .pptx cuyo tema y diseños de diapositiva copia Quarto. Parte del de Quarto, para que sus diseños tengan los nombres que Quarto espera:

Pídele a tu agente
Agrega una versión en PowerPoint: crea templates/acme-reference.pptx a partir del predeterminado de Quarto (`quarto pandoc -o templates/acme-reference.pptx --print-default-data-file reference.pptx`) con un script que fije los colores y la fuente de su tema a los de la presentación, agrega pptx a slides.qmd con `reference-doc`, renderiza y comprueba la cantidad de diapositivas y los colores del tema en el archivo.
Probablemente ejecute

quarto pandoc -o templates/acme-reference.pptx … · escribe un script que edita el tema de la plantilla · renderiza slides.pptx · cuenta las diapositivas, lee el tema

Quarto usa siete de los diseños de la plantilla por su nombre: Title Slide, Title and Content, Section Header, Two Content, Comparison, Content with Caption y Blank. La plantilla de tu propia organización funciona como documento de referencia si sus diseños llevan esos nombres; cámbiales el nombre en el patrón de diapositivas de PowerPoint si no los llevan. Una plantilla es un archivo binario, así que haz commit también del script que la crea: el script se puede revisar en un diff, y el archivo no.

Ten en cuenta lo que pierde PowerPoint. Las reglas Sass del tema no se aplican, los fragmentos se vuelven listas estáticas, .smaller y el pie de página no hacen nada, y Quarto 1.10.20 escribe el nombre de archivo de la imagen donde debería ir el texto alternativo de la figura; el proyecto terminado lo vuelve a agregar con un script corto después del renderizado. Abre el archivo de PowerPoint y revisa cada diapositiva, como lo hará quien lo reciba.

¿Dos minutos sin avanzar? Pega esto en tu agente. Respalda tu trabajo y lleva el proyecto hasta este punto; luego sigue leyendo desde aquí.

Catch me up: follow ../quarto-workshop/checkpoints/16-eval-slides/README.md
ImportantePruébalo

Construye la presentación, su tema y su prueba, el PDF y el archivo de PowerPoint, y preséntala una vez en la vista del presentador.

Terminaste cuando los títulos se leen como el argumento; cada diapositiva después del título tiene notas; la prueba de contraste pasa; el PDF tiene una página por diapositiva; y el archivo de PowerPoint se abre con los colores de la plantilla.

Resumen

  • Una presentación técnica es un argumento breve: una afirmación por diapositiva, cada título que la enuncia, el detalle en las notas y la decisión en la última diapositiva.
  • Pide las funciones por su nombre: notas de presentación, fragmentos, columnas, un tema, vista de impresión, un documento de referencia.
  • Los números de un título se calculan y sus palabras se protegen con guardas, como cualquier oración de un informe.
  • Revisa los colores con una prueba de contraste, contra el mínimo de WCAG de 4.5:1, para que una presentación legible siga siéndolo.
  • El PDF sale de la vista de impresión, revisado página por página; el PowerPoint sale de un documento de referencia, y pierde el tema, los fragmentos y el texto alternativo, así que ábrelo antes de enviarlo.

La presentación expone el caso una vez, en una sala. Los resultados también necesitan un lugar donde cualquiera pueda encontrarlos, con los colores de la empresa y con cada documento enlazado: un sitio.

Lecturas adicionales