13 White papers y referencias
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.
- 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.
13.1 De qué está hecho un white paper
| 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
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 "??".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ó:
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.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:
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í.
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:
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:
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.mdResumen
- 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: truehace 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
- Quarto, Cross References y Citations (consultados el 2026-11-18).
- Quarto, Typst custom formats y journal templates (consultados el 2026-11-18).
- Quarto, technical writing in the visual editor, sobre las citas desde Zotero (consultado el 2026-11-18).
- Citation Style Language, styles repository (consultado el 2026-11-18).
- Tom Fawcett, An introduction to ROC analysis, Pattern Recognition Letters 27 (2006), 861–874 (consultado el 2026-11-18).