13  White papers y referencias

Palabras clave

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

Un documento técnico (white paper) es la única salida que sale del edificio y tiene que sostenerse sola. Quien analiza datos para un cliente, quien asesora técnicamente a un inversionista o quien investiga con escepticismo lo leerá sin que estés en la sala, y lo revisará: si el método está declarado, si los números del texto coinciden con las tablas, si las referencias existen y dicen lo que el documento afirma que dicen. Para una startup, un white paper de benchmark o de evaluación suele ser lo más creíble que puede publicar, y lo más dañino si alguna de esas revisiones falla.

Este capítulo escribe el white paper de la evaluación: secciones numeradas, una ecuación, una tabla y figuras a las que el texto se refiere por número, citas en un estilo estándar que se leen igual en el PDF, el archivo de Word y la página web, referencias cuya existencia confirma un script, y una plantilla de la casa para el PDF. Los proyectos de Londres y del agua terminaban cada uno con un white paper opcional (la Sección 9.6, la Sección 23.7); este es el tratamiento completo, en la ruta principal.

En este capítulo
  • Nombrar las partes de un white paper técnico y la función de Quarto detrás de cada una: secciones numeradas, referencias cruzadas, citas, un estilo de citas y una plantilla.
  • Pedir un documento en el que cada figura, tabla y ecuación se cite por número, y revisar que cada referencia se resuelva en todos los formatos.
  • Citar solo lo que has abierto, en un mismo estilo de citas en HTML, Word y PDF, y revisar cada DOI con un script.
  • Darle al PDF una plantilla de la casa, y saber cuándo usar la de una revista.

Partes detu repositorio acme-eval al final del Capítulo 12, o checkpoints/17-eval-site/.

Construyeswhitepaper.qmd en PDF, Word y HTML, con references.bib, un estilo de citas, un revisor de referencias y una plantilla de la casa.

Punto de controlcheckpoints/18-eval-whitepaper/

13.1 De qué está hecho un white paper

Tabla 13.1: Las partes de un white paper, y cómo se llama cada una (Quarto 1.10.20).
Parte Quarto lo llama Revisas
secciones que quien lee puede citar number-sections: true, y ## Data {#sec-data} “Section 2” en el texto, en cada formato
una ecuación, citada $$ … $$ {#eq-auc} y @eq-auc “Equation 1”, una ecuación de verdad en Word
una tabla o una figura, citada una celda con etiqueta tbl-… o fig-…, y @tbl-… “Table 1”, “Figure 1”; ningún “??” en ninguna parte
citas [@key] en el texto, entradas en references.bib cada una aparece en la lista de referencias
un estilo de citas csl: con el nombre de un archivo de estilo, como el de APA el mismo estilo en cada formato
el mismo estilo en el PDF citeproc: true bajo typst: ningún segundo título “Bibliography”
un gestor de referencias un .bib exportado desde él, como el de Zotero las entradas exportadas coinciden con las fuentes
un aspecto de la casa un parcial de plantilla de Typst; un documento de referencia de Word el bloque de título y el pie de página, con la marca
el aspecto de una revista quarto use template quarto-journals/<name> las instrucciones de la propia revista

El white paper terminado remite por número a ecuaciones (3), tablas (1), figuras (2) y secciones (4). Una referencia que no se resuelve se renderiza como “??”, así que buscarla en cada formato es la revisión que alguien haría a ojo, hecha una sola vez: en los tres formatos del documento terminado, revisados el 2026-11-18, no encontró ninguna.

13.2 El documento

Pídele a tu agente
Crea whitepaper.qmd, un white paper técnico breve, en inglés, para clientes e inversionistas, solo a partir de outputs/: secciones numeradas (Introduction, Data, Method, Results, Limitations, Conclusion), el resumen escrito en el cuerpo y no en el YAML, la definición de ROC AUC como ecuación numerada, una tabla de resultados y la figura ROC, cada una citada en el texto con @eq-, @tbl- y @fig-, figuras vectoriales para el PDF (`fig-format: svg`), y una guarda en cada oración cuya redacción dependa de los resultados. Formatos html, typst y docx (el documento de referencia existente); agrégalo a la lista de renderizado del sitio y al listado con una descripción. Renderízalo y revisa que ninguna referencia cruzada muestre "??".
Probablemente ejecute

escribe whitepaper.qmd · lo agrega a _quarto.yml y al listado de la página de inicio · uv run quarto render whitepaper.qmd

Revísalo como lo haría su lector de fuera. Las referencias se resuelven: busca “??” en cada salida. Las figuras son vectoriales: en el PDF, haz zoom sobre las etiquetas de una figura; siguen nítidas. Los números coinciden: un número del texto de Results es igual al mismo número en la tabla. El resumen se sostiene solo: quien lea solo el resumen sabe qué se evaluó, el resultado principal y su límite principal.

13.3 Referencias que quien lee puede revisar

Una lista de referencias es un conjunto de afirmaciones: esta obra existe, y dice lo que decimos que dice. Un agente puede producir una referencia verosímil que no existe (la Sección 23.7), así que el prompt exige abrir cada una, y solo admite lo que se confirmó:

Pídele a tu agente
Cita, desde references.bib, el conjunto de datos, Moro et al. (2014), Mitchell et al. (2019) y los artículos en los que se basan el análisis ROC, el bootstrap y la calibración. Busca cada DOI con la API de Crossref, o la de DataCite para el conjunto de datos, ábrelo, y agrega solo las entradas cuyos autores, título y año hayas podido confirmar. Descarga apa.csl del repositorio oficial de estilos CSL, úsalo con `citeproc: true` para typst, renderiza los tres formatos y revisa que sus listas de referencias coincidan.
Probablemente ejecute

consulta Crossref · edita references.bib · descarga csl/apa.csl · renderiza tres formatos

El references.bib del proyecto, que el white paper comparte con la ficha del modelo, reúne siete trabajos, todos citados por el white paper, cada uno confirmado en su fuente el 2026-11-18:

Tabla 13.2: Las referencias del proyecto, tomadas del references.bib terminado, y los documentos que citan cada una.
Clave Año DOI Citado por
moro2014bank 2014 10.24432/C5K306 white paper, ficha
moro2014datadriven 2014 10.1016/j.dss.2014.03.001 white paper, ficha
mitchell2019modelcards 2019 10.1145/3287560.3287596 white paper, ficha
equalityact2010s4 2010 ninguno: revisado a mano en su fuente white paper, ficha
fawcett2006roc 2006 10.1016/j.patrec.2005.10.010 white paper
efron1979bootstrap 1979 10.1214/aos/1176344552 white paper
niculescumizil2005calibration 2005 10.1145/1102351.1102430 white paper

Un estilo de citas es un archivo. El repositorio oficial del Citation Style Language guarda miles, entre ellos APA e IEEE y los de la mayoría de las revistas, cada uno con una licencia Creative Commons; descarga el que tus lectores esperan y nómbralo en csl:; en el _quarto.yml de un sitio, para que todos los documentos del sitio citen igual, como hace el proyecto terminado. Los gestores de referencias como Zotero exportan el mismo formato .bib, así que una biblioteca existente puede ser la fuente, y el editor visual de Quarto puede insertar citas directamente desde una biblioteca de Zotero. De cualquier manera, la revisión es la misma: cada entrada se abrió, y cada afirmación que respalda se leyó allí.

AdvertenciaError frecuente

Trampas encontradas al construir y probar las referencias. Sin citeproc: true, el PDF le pasa las citas al procesador propio de Typst, que imprimió otro estilo y un segundo título “Bibliography”. El estilo de APA pone en minúsculas las palabras de los títulos, así que los nombres propios como “Bank Marketing” tienen que ir entre llaves en el .bib para conservar sus mayúsculas. El DOI del conjunto de datos está registrado en DataCite, no en Crossref, y su registro listaba mal a sus autores, así que se cita como lo da la propia página del repositorio. Un artículo cuyo DOI se resolvía no se pudo abrir en absoluto; no se cita, y la medida que introdujo se define en el texto: cita lo que has leído. Y en el PDF, el año abreviado de una conferencia, “ICML ’05”, salió con una comilla de apertura, porque Typst curva un apóstrofo recto según sus propias reglas. El white paper terminado deja esos nombres abreviados fuera de su .bib; en la prueba, un apóstrofo curvo en el .bib, con el formato escrito typst-smart en lugar de typst, lo mantuvo bien.

13.4 Una revisión para cada DOI

Abrir cada referencia a mano es la primera revisión; un script que la repite antes de cada versión es la segunda, y la que sobrevive a que alguien del equipo agregue una entrada con prisa:

Pídele a tu agente
Escribe scripts/check_refs.py: para cada entrada de references.bib que tenga DOI, busca el registro (en Crossref, o en DataCite para un DOI de DataCite) y falla si el DOI no se resuelve o si el año, el apellido del primer autor o el título no coinciden con la entrada. Ejecútalo.

El script necesita la red, así que es una revisión que ejecutas antes de publicar, no parte del renderizado, que tiene que funcionar sin conexión. Pruébalo una vez sobre una copia del .bib rota a propósito: un año equivocado, un título cambiado y un DOI que no existe tienen que hacerlo fallar, cada uno.

13.5 Una plantilla de la casa para el PDF

Quarto escribe un PDF de Typst a partir de una plantilla hecha de partes con nombre, los parciales de plantilla, y puedes reemplazar una parte por la tuya. La que da estilo al documento es typst-show.typ; un reemplazo puede darle al documento un bloque de título con el logo de la empresa y una etiqueta, un encabezado de página y números de página, en los colores de la marca, que Quarto le define a partir de _brand.yml:

Pídele a tu agente
Dale al PDF un estilo de la casa: un parcial de Typst, templates/whitepaper/typst-show.typ, usado desde el formato typst de whitepaper.qmd con `template-partials`, que muestre brand/logo.svg, la etiqueta "Technical white paper", la empresa y la fecha en un bloque de título, y "page n of N" en el pie de página, en los colores de la marca. Renderiza el PDF y mira su primera página.

Los colores y el logo de la marca llegan al parcial, pero su nombre no: en Quarto 1.10.20 solo la tipografía de la marca se vuelve una variable de la plantilla, así que el white paper terminado nombra a la empresa en un campo company: de su propio encabezado YAML. Renderiza el PDF de todo el sitio, o borra lo que un renderizado de una sola página con keep-typ deja en la carpeta del proyecto: en la prueba escribió una carpeta site_libs/ y la fuente .typ junto a las fuentes. Una trampa del propio Typst: en un patrón de número de página como "1 of 1", las letras también son contadores, así que un patrón escrito "page 1 of 1" imprimió “pbge” en la segunda página; deja las palabras fuera del patrón. Quarto 1.10.20 solo acepta sus propios nombres de parciales (typst-show.typ, typst-template.typ, page.typ y cuatro más); cualquier otro nombre detiene el renderizado. Cuando una revista o una conferencia tiene su propio formato, usa el suyo en lugar de una plantilla de la casa: las plantillas de revistas de Quarto se instalan con quarto use template quarto-journals/<name>, y las instrucciones del lugar de publicación van primero.

¿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/18-eval-whitepaper/README.md
ImportantePruébalo

Escribe el documento, cita y revisa sus referencias, y dale al PDF la plantilla de la casa.

Terminaste cuando cada referencia cruzada se resuelve en el PDF, el archivo de Word y la página web; las tres listas de referencias coinciden; check_refs.py no informa ningún problema; y el PDF abre con el bloque de título de la casa.

Resumen

  • Un white paper se lee sin ti y lo revisan desconocidos: secciones numeradas, figuras, tablas y ecuaciones con referencias cruzadas, y referencias que existen.
  • Las referencias cruzadas son etiquetas (sec-, tbl-, fig-, eq-), y el renderizado muestra como “??” cualquiera que falle.
  • Un archivo de estilo CSL fija el estilo de citas; citeproc: true hace que un PDF de Typst también lo use.
  • Cita solo lo que has abierto, y deja que un script confirme cada DOI antes de cada versión.
  • Un parcial de plantilla de Typst le da al PDF un aspecto de la casa a partir de la marca; la plantilla de una revista lo reemplaza cuando el lugar de publicación tiene una.

Con eso se completa el conjunto de la evaluación: un informe, una ficha del modelo, una presentación, un sitio y un white paper, todos a partir de una sola ejecución de un solo script.

Lecturas adicionales